refactor: clean-up and handle interface case

---
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: passed
  - 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

@@ -40,15 +40,6 @@ var rule = require( '@stdlib/_tools/eslint/rules/tsdoc-doctest' );
 
 [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.
 
-The rule:
-
--   Extracts `@example` blocks from TSDoc comments in TypeScript declaration files
--   Loads the actual JavaScript package corresponding to the declaration file
--   Executes the example code in a sandboxed environment
--   Compares the actual output with the expected return annotations
--   Supports functions, constants, classes, and namespace objects
--   Handles `// returns`, `// throws`, and `// =>` annotations
-
 **Bad**:
 
 <!-- eslint-disable stdlib/tsdoc-doctest -->
@@ -140,9 +131,7 @@ var result = linter.verify( code, {
 }, {
     'filename': 'lib/node_modules/@stdlib/math/base/special/abs/docs/types/index.d.ts'
 });
-
-console.log( result );
-/* =>
+/* returns
     [
         {
             'ruleId': 'tsdoc-doctest',
@@ -166,10 +155,11 @@ console.log( result );
 
 ## Notes
 
--   The rule requires that the TypeScript declaration file path follows the stdlib convention: `lib/node_modules/@stdlib/<package>/docs/types/index.d.ts`
 -   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 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).
 
 </section>
 

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

@@ -26,6 +26,7 @@ var RE_DECLARE_VAR = /declare\s+var\s+([a-zA-Z_$][a-zA-Z0-9_$]*)\s*:/;
 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_$]*/;
 var RE_DECLARE_CONST = /declare\s+const\s+([a-zA-Z_$][a-zA-Z0-9_$]*)\s*:/;
+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 //
@@ -38,6 +39,7 @@ var RE_DECLARE_CONST = /declare\s+const\s+([a-zA-Z_$][a-zA-Z0-9_$]*)\s*:/;
 * @param {string} sourceText - TypeScript declaration source text to parse for identifier names
 */
 function addPackageToScope( scope, pkg, sourceText ) {
+	var interfaceMatch;
 	var namespaceMatch;
 	var funcMatch;
 
@@ -55,6 +57,13 @@ function addPackageToScope( scope, pkg, sourceText ) {
 		if ( funcMatch ) {
 			scope[ funcMatch[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:
+			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 );

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

@@ -46,7 +46,6 @@ var RE_TSDOC = /\/\*\*[\s\S]+?\*\//g;
 var RE_EXAMPLE = /@example\s*([\s\S]*?)(?=\n\s*@\w|\*\/|$)/g;
 var RE_NEWLINE = /\r?\n/g;
 var RE_ANNOTATION = /(?:\n|^)(?:var|let|const)? ?([a-zA-Z0-9._]+) ?=[^;]*;\n\/\/ ?(returns|([A-Za-z][A-Za-z_0-9]*)? ?=>|throws) ?([\s\S]*?)(\n|$)/g;
-var RE_CONSOLE = /console\.(?:dir|error|log)/;
 var RE_COMMENT_PREFIX = /^\s*\*\s?/gm;
 var RE_SPECIAL_CHARS = /[.*+?^${}()|[\]\\]/g;
 var regexCache = {};
@@ -201,27 +200,23 @@ function processExampleCode( code, commentIdx, comments, scope, report, opts, so
 	var type;
 	var loc;
 	var msg;
-	var out;
 	var arr;
 
-	// VM context already created in validate() function
-
 	last = 0;
 	RE_ANNOTATION.lastIndex = 0;
 	try {
 		arr = RE_ANNOTATION.exec( code );
 		while ( !isNull( arr ) ) {
-			// Run intermediary code
 			intermediary = code.substring( last, arr.index );
 			last = arr.index + arr[ 0 ].length;
 			if ( intermediary ) {
 				vm.runInContext( intermediary, scope );
 			}
 
-			// Calculate line of current code chunk within the comment
+			// Calculate line of current code chunk within the comment:
 			commentStartIdx = sourceCode.text.indexOf( comments[ commentIdx ] );
 
-			// Find the annotation in the original comment
+			// Find the annotation in the original comment:
 			returnAnnotationPattern = getAnnotationRegex( arr[ 2 ], arr[ 4 ] );
 			annotationMatch = comments[ commentIdx ].match( returnAnnotationPattern );
 
@@ -242,14 +237,12 @@ function processExampleCode( code, commentIdx, comments, scope, report, opts, so
 				}
 			};
 
-			// Run code preceding return annotation
+			// Run code preceding return annotation:
 			try {
-				out = vm.runInContext( arr[ 0 ], scope );
-				if ( RE_CONSOLE.test( arr[ 1 ] ) ) {
-					actual = out;
-				} else {
-					actual = scope[ arr[ 1 ] ];
-				}
+				vm.runInContext( arr[ 0 ], scope );
+
+				// For assignment-form examples, read the assigned variable from scope:
+				actual = scope[ arr[ 1 ] ];
 				if ( arr[ 3 ] ) {
 					actual = vm.runInContext( arr[ 3 ], scope );
 				}
@@ -259,13 +252,13 @@ function processExampleCode( code, commentIdx, comments, scope, report, opts, so
 					opts.includeDecimal = isNumber( actual ) && contains( expected, '.' );
 					replacement = createAnnotationValue( actual, opts );
 
-					// Find the position of the return value in the annotation
+					// Find the position of the return value in the annotation:
 					valueStartInAnnotation = annotationMatch[ 0 ].indexOf( arr[ 4 ] );
 					loc.range = [
-						// Position of arr[4] start in source text
+						// Position of arr[4] start in source text:
 						commentStartIdx + codeIdx + valueStartInAnnotation,
 
-						// Position of arr[4] end in source text
+						// Position of arr[4] end in source text:
 						commentStartIdx + codeIdx + valueStartInAnnotation + arr[ 4 ].length
 					];
 					report( loc, msg, replacement );
@@ -286,7 +279,7 @@ function processExampleCode( code, commentIdx, comments, scope, report, opts, so
 				if ( msg ) {
 					replacement = ( arr[ 3 ] ) ? findName( scope, arr[ 4 ] ) + ' => ' + arr[ 4 ] : 'throws '+type;
 
-					// Find annotation part in the match (after "// ")
+					// Find annotation part in the match (after "// "):
 					annotationStart = arr[ 0 ].indexOf( '// ' ) + 3;
 					annotationEnd = arr[ 0 ].length - arr[ 5 ].length;
 					loc.range = [
@@ -299,13 +292,12 @@ function processExampleCode( code, commentIdx, comments, scope, report, opts, so
 			arr = RE_ANNOTATION.exec( code );
 		}
 
-		// Run any remaining code
 		remaining = code.substring( last );
 		if ( remaining ) {
 			vm.runInContext( remaining, scope );
 		}
 	} catch ( err ) {
-		// Calculate the line number for the example that caused the error
+		// Calculate the line number for the example that caused the error...
 		exampleStartIdx = sourceCode.text.indexOf( comments[ commentIdx ] );
 		exampleIdx = comments[ commentIdx ].indexOf( code );
 		line = countLines( sourceCode.text.substring( 0, exampleStartIdx + exampleIdx ) ) + 1;
@@ -320,7 +312,7 @@ function processExampleCode( code, commentIdx, comments, scope, report, opts, so
 			}
 		};
 
-		// Do not report errors in TypeScript declaration files due to modules failing to load
+		// Do not report errors in TypeScript declaration files due to modules failing to load:
 		if ( contains( err.message, 'Cannot find module' ) ) {
 			return;
 		}
@@ -344,7 +336,7 @@ function main( context ) {
 	filename = context.getFilename();
 	options = context.options[ 0 ] || {};
 
-	// Only process TypeScript declaration files
+	// Only process TypeScript declaration files:
 	if ( !filename.endsWith( '.d.ts' ) ) {
 		return {};
 	}
@@ -401,7 +393,7 @@ function main( context ) {
 		var i;
 		var j;
 
-		// Clear caches to prevent memory leaks
+		// Clear caches to prevent memory leaks:
 		regexCache = {};
 		lineCountCache = {};
 
@@ -468,6 +460,7 @@ function main( context ) {
 
 rule = {
 	'meta': {
+		'type': 'problem',
 		'docs': {
 			'description': 'ensure return annotations in TSDoc examples match the actual output'
 		},

lib/node_modules/@stdlib/_tools/eslint/rules/tsdoc-doctest/test/fixtures/invalid.js

@@ -74,6 +74,51 @@ test = {
 };
 invalid.push( test );
 
+test = {
+	'code': [
+		'/**',
+		'* Abbreviated Int32Vector example (invalid).',
+		'*',
+		'* @example',
+		"* var numel = require( '@stdlib/ndarray/numel' );",
+		'*',
+		'* var arr = new Int32Vector();',
+		'* // returns <ndarray>',
+		'*',
+		'* var len = numel( arr );',
+		'* // returns 1',
+		'*/',
+		'declare var ctor: Int32Vector;',
+		'',
+		'export = ctor;'
+	].join( '\n' ),
+	'filename': join( ROOT_DIR, 'lib/node_modules/@stdlib/ndarray/vector/int32/docs/types/index.d.ts' ),
+	'output': [
+		'/**',
+		'* Abbreviated Int32Vector example (invalid).',
+		'*',
+		'* @example',
+		"* var numel = require( '@stdlib/ndarray/numel' );",
+		'*',
+		'* var arr = new Int32Vector();',
+		'* // returns <ndarray>',
+		'*',
+		'* var len = numel( arr );',
+		'* // returns 0',
+		'*/',
+		'declare var ctor: Int32Vector;',
+		'',
+		'export = ctor;'
+	].join( '\n' ),
+	'errors': [
+		{
+			'message': 'Displayed return value is `1`, but expected `0` instead',
+			'type': null
+		}
+	]
+};
+invalid.push( test );
+
 test = {
 	'code': [
 		'/**',

lib/node_modules/@stdlib/_tools/eslint/rules/tsdoc-doctest/test/fixtures/valid.js

@@ -156,6 +156,28 @@ test = {
 };
 valid.push( test );
 
+test = {
+	'code': [
+		'/**',
+		'* Abbreviated Int32Vector example.',
+		'*',
+		'* @example',
+		"* var numel = require( '@stdlib/ndarray/numel' );",
+		'*',
+		'* var arr = new Int32Vector();',
+		'* // returns <ndarray>',
+		'*',
+		'* var len = numel( arr );',
+		'* // returns 0',
+		'*/',
+		'declare var ctor: Int32Vector;',
+		'',
+		'export = ctor;'
+	].join( '\n' ),
+	'filename': join( ROOT_DIR, 'lib/node_modules/@stdlib/ndarray/vector/int32/docs/types/index.d.ts' )
+};
+valid.push( test );
+
 
 // EXPORTS //