Optimizes iterable & string utils to improve perf

 - Replaces generator utils w/ optimized, class-based iterator versions
 - Adds unit tests for new iterator implementations
 - Adds rough benchmarking framework, powered by `tinybench`

Author: eamodio

CONTRIBUTING.md

@@ -251,3 +251,141 @@ To add new icons to the GL Icons font follow the steps below:
   ```
 
 Once you've finished copy the new `glicons.woff2?<uuid>` URL from `src/webviews/apps/shared/glicons.scss` and search and replace the old references with the new one.
+
+## Testing
+
+GitLens uses VS Code's testing infrastructure for unit and integration tests.
+
+### Running Tests
+
+```bash
+# Run all tests
+pnpm run test
+
+# Run E2E tests
+pnpm run test:e2e
+
+# Build test files (required before running tests)
+pnpm run build:tests
+
+# Watch mode for tests during development
+pnpm run watch:tests
+```
+
+### Writing Tests
+
+Tests are co-located with source files in `__tests__/` directories:
+
+```
+src/
+  └── system/
+      ├── string.ts
+      └── __tests__/
+          └── string.test.ts  ← Test file
+```
+
+Create test files using the naming pattern `*.test.ts`:
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { functionToTest } from '../module';
+
+describe('functionToTest', () => {
+	it('should handle basic case', () => {
+		const result = functionToTest('input');
+		expect(result).toBe('expected output');
+	});
+
+	it('should handle edge cases', () => {
+		expect(functionToTest('')).toBe('');
+		expect(functionToTest(null)).toBeUndefined();
+	});
+});
+```
+
+### Test Best Practices
+
+- **Co-locate tests**: Place tests in `__tests__/` directories next to the code they test
+- **Descriptive names**: Use clear test names that describe what is being tested
+- **Test behavior**: Focus on testing behavior and outputs, not implementation details
+- **Edge cases**: Always test edge cases, empty inputs, and error conditions
+- **Mock dependencies**: Use mocks for external dependencies (VS Code API, file system, etc.)
+- **Keep tests fast**: Unit tests should run quickly; use mocks to avoid slow operations
+
+### Debugging Tests
+
+Use VS Code's built-in test runner:
+
+1. Open the Testing view in the sidebar
+2. Click the debug icon next to any test to debug it
+3. Set breakpoints in test files or source code
+4. Use the Debug Console to inspect variables
+
+Alternatively, use the provided launch configurations:
+
+- Open the Run and Debug view
+- Select a test-related launch configuration
+- Press `F5` to start debugging
+
+## Benchmarking
+
+GitLens includes a benchmarking framework for measuring and comparing performance of critical code paths.
+
+### Running Benchmarks
+
+```bash
+# List all available benchmarks
+pnpm run benchmark:list
+
+# Run all benchmarks
+pnpm run benchmark
+
+# Run a specific benchmark by name
+pnpm run benchmark <name>
+```
+
+### Creating New Benchmarks
+
+Benchmarks are automatically discovered when placed in `__tests__/` directories:
+
+1. Create a file named `*.benchmark.ts` in any `__tests__/` directory
+2. Use [tinybench](https://github.com/tinylibs/tinybench) to write your benchmark:
+
+```typescript
+import { Bench } from 'tinybench';
+
+async function runBenchmark() {
+	console.log('MY FEATURE BENCHMARK');
+
+	const bench = new Bench({ time: 100 });
+
+	bench
+		.add('Method A', () => {
+			// Code to benchmark
+		})
+		.add('Method B', () => {
+			// Alternative implementation
+		});
+
+	await bench.run();
+
+	// Display results
+	for (const task of bench.tasks) {
+		console.log(`${task.name}: ${task.result?.hz.toLocaleString()} ops/sec`);
+	}
+}
+
+runBenchmark();
+```
+
+3. Run your benchmark: `pnpm run benchmark <name>`
+
+### Best Practices
+
+- **Use realistic data**: Generate test data matching real-world patterns
+- **Test multiple scenarios**: Benchmark with different data sizes (small, medium, large)
+- **Measure complete operations**: Include all relevant work in benchmarks
+- **Display clear results**: Show ops/sec, average time, and margin of error
+- **Focus on hot paths**: Benchmark performance-critical code
+
+See the full [Benchmarking Guide](docs/benchmarking.md) for detailed information and the `src/system/__tests__/string.benchmark.ts` example.

package.json

@@ -25886,6 +25886,8 @@
 		"build:webviews:quick": "node ./scripts/compile-composer-templates.mjs && webpack --mode development --config-name webviews:common --config-name webviews --env skipLint",
 		"build:icons": "pnpm run icons:svgo && pnpm fantasticon && pnpm run icons:apply && pnpm run icons:export",
 		"build:tests": "node ./scripts/esbuild.tests.mjs",
+		"benchmark": "node ./scripts/runBenchmark.mjs",
+		"benchmark:list": "node ./scripts/runBenchmark.mjs --list",
 		"// Extracts the contributions from package.json into contributions.json": "//",
 		"extract:contributions": "node --experimental-strip-types ./scripts/generateContributions.mts --extract",
 		"// Generates contributions in contributions.json into package.json": "//",
@@ -26039,6 +26041,7 @@
 		"sinon": "21.0.0",
 		"svgo": "4.0.0",
 		"terser-webpack-plugin": "5.3.14",
+		"tinybench": "5.0.1",
 		"ts-loader": "9.5.4",
 		"typescript": "5.9.3",
 		"typescript-eslint": "8.46.0",

pnpm-lock.yaml

@@ -19,7 +19,7 @@ async function buildTests(target) {
 	/** @type BuildOptions | WatchOptions */
 	const config = {
 		bundle: true,
-		entryPoints: ['src/**/__tests__/**/*.test.ts'],
+		entryPoints: ['src/**/__tests__/**/*.test.ts', 'src/**/__tests__/**/*.benchmark.ts'],
 		entryNames: '[dir]/[name]',
 		external: ['vscode'],
 		format: 'cjs',

scripts/esbuild.tests.mjs

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+
+/**
+ * Benchmark runner for GitLens
+ *
+ * Usage:
+ *   pnpm run benchmark              # Run all benchmarks
+ *   pnpm run benchmark string       # Run specific benchmark by name
+ *   pnpm run benchmark --list       # List all available benchmarks
+ */
+
+import { execSync } from 'child_process';
+import { existsSync, readdirSync, statSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join, basename } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const rootDir = join(__dirname, '..');
+
+// Parse command line arguments
+const args = process.argv.slice(2);
+const shouldList = args.includes('--list') || args.includes('-l');
+const specificBenchmark = args.find(arg => !arg.startsWith('--'));
+
+/**
+ * Find all benchmark files in the codebase
+ */
+function findBenchmarkFiles() {
+	const benchmarks = [];
+	const testDirs = [];
+
+	// Find all __tests__ directories
+	function findTestDirs(dir) {
+		const entries = readdirSync(dir, { withFileTypes: true });
+		for (const entry of entries) {
+			if (entry.name === 'node_modules' || entry.name === 'dist' || entry.name === 'out') continue;
+
+			const fullPath = join(dir, entry.name);
+			if (entry.isDirectory()) {
+				if (entry.name === '__tests__') {
+					testDirs.push(fullPath);
+				}
+				findTestDirs(fullPath);
+			}
+		}
+	}
+
+	findTestDirs(join(rootDir, 'src'));
+
+	// Find benchmark files in test directories
+	for (const testDir of testDirs) {
+		const entries = readdirSync(testDir);
+		for (const entry of entries) {
+			if (entry.endsWith('.benchmark.ts')) {
+				const fullPath = join(testDir, entry);
+				const relativePath = fullPath.replace(rootDir, '').replace(/\\/g, '/').substring(1);
+				const name = basename(entry, '.benchmark.ts');
+
+				benchmarks.push({
+					name,
+					sourcePath: relativePath,
+					outputPath: relativePath
+						.replace('src/', 'out/tests/')
+						.replace('.ts', '.js'),
+				});
+			}
+		}
+	}
+
+	return benchmarks;
+}
+
+/**
+ * List all available benchmarks
+ */
+function listBenchmarks(benchmarks) {
+	console.log('Available benchmarks:\n');
+	for (const benchmark of benchmarks) {
+		console.log(`  ${benchmark.name.padEnd(20)} - ${benchmark.sourcePath}`);
+	}
+	console.log(`\nTotal: ${benchmarks.length} benchmark(s)`);
+	console.log('\nUsage:');
+	console.log('  pnpm run benchmark              # Run all benchmarks');
+	console.log('  pnpm run benchmark <name>       # Run specific benchmark');
+	console.log('  pnpm run benchmark --list       # Show this list');
+}
+
+/**
+ * Build benchmarks
+ */
+function buildBenchmarks() {
+	console.log('Building benchmarks...\n');
+	try {
+		execSync(`node ${join(rootDir, 'scripts', 'esbuild.tests.mjs')}`, {
+			stdio: 'inherit',
+			cwd: rootDir,
+		});
+	} catch (error) {
+		console.error('Error building benchmarks:', error.message);
+		process.exit(1);
+	}
+}
+
+/**
+ * Run a specific benchmark
+ */
+function runBenchmark(benchmark) {
+	const benchmarkPath = join(rootDir, benchmark.outputPath);
+
+	if (!existsSync(benchmarkPath)) {
+		console.error(`Error: Benchmark file not found at ${benchmarkPath}`);
+		console.error('Make sure the build completed successfully.');
+		process.exit(1);
+	}
+
+	console.log(`\nRunning benchmark: ${benchmark.name}`);
+	console.log(`Source: ${benchmark.sourcePath}\n`);
+
+	try {
+		execSync(`node "${benchmarkPath}"`, { stdio: 'inherit', cwd: rootDir });
+	} catch (error) {
+		console.error(`Error running benchmark ${benchmark.name}:`, error.message);
+		process.exit(1);
+	}
+}
+
+/**
+ * Main execution
+ */
+function main() {
+	const benchmarks = findBenchmarkFiles();
+
+	if (benchmarks.length === 0) {
+		console.log('No benchmarks found.');
+		console.log('Create benchmark files named *.benchmark.ts in __tests__ directories.');
+		process.exit(0);
+	}
+
+	// Handle --list flag
+	if (shouldList) {
+		listBenchmarks(benchmarks);
+		process.exit(0);
+	}
+
+	// Build benchmarks
+	buildBenchmarks();
+
+	// Run specific benchmark if specified
+	if (specificBenchmark) {
+		const benchmark = benchmarks.find(b => b.name === specificBenchmark);
+		if (!benchmark) {
+			console.error(`Error: Benchmark "${specificBenchmark}" not found.`);
+			console.error('\nAvailable benchmarks:');
+			for (const b of benchmarks) {
+				console.error(`  - ${b.name}`);
+			}
+			process.exit(1);
+		}
+
+		runBenchmark(benchmark);
+	} else {
+		// Run all benchmarks
+		console.log(`\nRunning ${benchmarks.length} benchmark(s)...\n`);
+
+		for (let i = 0; i < benchmarks.length; i++) {
+			if (i > 0) {
+				console.log('\n' + '━'.repeat(80) + '\n');
+			}
+			runBenchmark(benchmarks[i]);
+		}
+	}
+
+	console.log('\n✓ All benchmarks completed successfully!\n');
+}
+
+main();