Merge pull request #2 from GPTI314/claude/review-enhance-optimization-017dXcB4PEKc8xx7PtGYq5nm

Claude/review enhance optimization 017d xc b4 pe kc8xx7 pt g yq5nm

Author: GPTI314

extension/src/goMain.ts

@@ -83,6 +83,29 @@ interface ExtensionTestAPI {
 	globalState: vscode.Memento;
 }
 
+/**
+ * Extension activation entry point called by VS Code when the Go extension loads.
+ * This is the main initialization function that sets up all Go development features.
+ *
+ * Activation sequence:
+ * 1. Initialize global and workspace state
+ * 2. Configure GOROOT and environment variables
+ * 3. Build and install vscgo helper tool
+ * 4. Register all extension commands
+ * 5. Set up language features (code lens, formatting, testing, etc.)
+ * 6. Start gopls language server (if enabled)
+ * 7. Install missing/outdated Go tools
+ * 8. Configure telemetry and surveys
+ *
+ * @param ctx - VS Code extension context providing subscriptions, storage, and paths
+ * @returns ExtensionAPI for production use or ExtensionTestAPI for testing
+ *
+ * @example
+ * // Called automatically by VS Code, not by user code
+ * // Returns API that can be accessed by other extensions via:
+ * const goExt = vscode.extensions.getExtension('golang.go');
+ * const api = await goExt?.activate();
+ */
 export async function activate(ctx: vscode.ExtensionContext): Promise<ExtensionAPI | ExtensionTestAPI | undefined> {
 	if (process.env['VSCODE_GO_IN_TEST'] === '1') {
 		// TODO: VSCODE_GO_IN_TEST was introduced long before we learned about
@@ -240,6 +263,26 @@ export async function activate(ctx: vscode.ExtensionContext): Promise<ExtensionA
 	return extensionAPI;
 }
 
+/**
+ * Extension deactivation called by VS Code when the extension is being unloaded.
+ * Performs cleanup to ensure no resources are leaked and all background processes are stopped.
+ *
+ * Cleanup operations (all run in parallel):
+ * - Stop gopls language server and wait for graceful shutdown
+ * - Cancel any running test sessions
+ * - Kill any active pprof profiling processes
+ * - Clean up temporary directories and files
+ * - Dispose status bar items
+ * - Flush and dispose telemetry reporter
+ *
+ * @returns Promise that resolves when all cleanup is complete
+ *
+ * @example
+ * // Called automatically by VS Code when:
+ * // - Extension is disabled
+ * // - Extension is being updated
+ * // - VS Code is shutting down
+ */
 export function deactivate() {
 	return Promise.all([
 		goCtx.languageClient?.stop(),

extension/src/language/goLanguageServer.ts

@@ -85,7 +85,7 @@ export interface LanguageServerConfig {
 	modtime?: Date;
 	enabled: boolean;
 	flags: string[];
-	env: any;
+	env: NodeJS.ProcessEnv;
 	features: {
 		// A custom formatter can be configured to run instead of gopls.
 		// This is enabled when the user has configured a specific format
@@ -95,6 +95,12 @@ export interface LanguageServerConfig {
 	checkForUpdates: string;
 }
 
+/**
+ * Represents a configuration object for gopls or Go settings.
+ * This is a flexible object that can contain any configuration key-value pairs.
+ */
+export type ConfigurationObject = { [key: string]: unknown };
+
 export interface ServerInfo {
 	Name: string;
 	Version?: string;
@@ -382,8 +388,27 @@ type VulncheckEvent = {
 	message?: string;
 };
 
-// buildLanguageClient returns a language client built using the given language server config.
-// The returned language client need to be started before use.
+/**
+ * Builds a VS Code Language Server Protocol (LSP) client for gopls.
+ * The returned client is configured but not started - caller must call .start() on it.
+ *
+ * This function sets up:
+ * - Output channels for server logs and traces
+ * - Language server executable options (path, flags, environment)
+ * - Client options (document selectors, middleware, synchronization)
+ * - Progress handlers for gopls operations
+ * - Command execution middleware
+ * - Configuration synchronization with gopls
+ *
+ * @param goCtx - Go extension context containing output channels and state
+ * @param cfg - Language server configuration with path, flags, and features
+ * @returns Configured GoLanguageClient instance ready to be started
+ *
+ * @example
+ * const cfg = await buildLanguageServerConfig(getGoConfig());
+ * const client = await buildLanguageClient(goCtx, cfg);
+ * await client.start(); // Start the language server
+ */
 export async function buildLanguageClient(
 	goCtx: GoExtensionContext,
 	cfg: LanguageServerConfig
@@ -408,7 +433,7 @@ export async function buildLanguageClient(
 
 	// TODO(hxjiang): deprecate special handling for async call gopls.run_govulncheck.
 	let govulncheckTerminal: IProgressTerminal | undefined;
-	const pendingVulncheckProgressToken = new Map<ProgressToken, any>();
+	const pendingVulncheckProgressToken = new Map<ProgressToken, { URI: string }>();
 	const onDidChangeVulncheckResultEmitter = new vscode.EventEmitter<VulncheckEvent>();
 
 	// VSCode-Go prepares the information needed to start the language server.
@@ -850,12 +875,12 @@ export async function buildLanguageClient(
 // and selects only those the user explicitly specifies in their settings.
 // This returns a new object created based on the filtered properties of workspaceConfig.
 // Exported for testing.
-export function filterGoplsDefaultConfigValues(workspaceConfig: any, resource?: vscode.Uri): any {
+export function filterGoplsDefaultConfigValues(workspaceConfig: ConfigurationObject, resource?: vscode.Uri): ConfigurationObject {
 	if (!workspaceConfig) {
 		workspaceConfig = {};
 	}
 	const cfg = getGoplsConfig(resource);
-	const filtered = {} as { [key: string]: any };
+	const filtered: ConfigurationObject = {};
 	for (const [key, value] of Object.entries(workspaceConfig)) {
 		if (typeof value === 'function') {
 			continue;
@@ -888,7 +913,7 @@ export function filterGoplsDefaultConfigValues(workspaceConfig: any, resource?:
 //   - go.buildTags and go.buildFlags are passed as gopls.build.buildFlags
 //     if goplsWorkspaceConfig doesn't explicitly set it yet.
 // Exported for testing.
-export function passGoConfigToGoplsConfigValues(goplsWorkspaceConfig: any, goWorkspaceConfig: any): any {
+export function passGoConfigToGoplsConfigValues(goplsWorkspaceConfig: ConfigurationObject, goWorkspaceConfig: ConfigurationObject): ConfigurationObject {
 	if (!goplsWorkspaceConfig) {
 		goplsWorkspaceConfig = {};
 	}
@@ -913,10 +938,10 @@ export function passGoConfigToGoplsConfigValues(goplsWorkspaceConfig: any, goWor
 // If this is for the nightly extension, we also request to activate features under experiments.
 async function adjustGoplsWorkspaceConfiguration(
 	cfg: LanguageServerConfig,
-	workspaceConfig: any,
+	workspaceConfig: ConfigurationObject,
 	section?: string,
 	resource?: vscode.Uri
-): Promise<any> {
+): Promise<ConfigurationObject> {
 	// We process only gopls config
 	if (section !== 'gopls') {
 		return workspaceConfig;
@@ -940,7 +965,7 @@ async function adjustGoplsWorkspaceConfiguration(
 	return workspaceConfig;
 }
 
-async function passInlayHintConfigToGopls(cfg: LanguageServerConfig, goplsConfig: any, goConfig: any) {
+async function passInlayHintConfigToGopls(cfg: LanguageServerConfig, goplsConfig: ConfigurationObject, goConfig: vscode.WorkspaceConfiguration): Promise<ConfigurationObject> {
 	const goplsVersion = await getLocalGoplsVersion(cfg);
 	if (!goplsVersion) return goplsConfig ?? {};
 	const version = semver.parse(goplsVersion.version);
@@ -953,7 +978,7 @@ async function passInlayHintConfigToGopls(cfg: LanguageServerConfig, goplsConfig
 	return goplsConfig;
 }
 
-async function passVulncheckConfigToGopls(cfg: LanguageServerConfig, goplsConfig: any, goConfig: any) {
+async function passVulncheckConfigToGopls(cfg: LanguageServerConfig, goplsConfig: ConfigurationObject, goConfig: vscode.WorkspaceConfiguration): Promise<ConfigurationObject> {
 	const goplsVersion = await getLocalGoplsVersion(cfg);
 	if (!goplsVersion) return goplsConfig ?? {};
 	const version = semver.parse(goplsVersion.version);
@@ -966,7 +991,7 @@ async function passVulncheckConfigToGopls(cfg: LanguageServerConfig, goplsConfig
 	return goplsConfig;
 }
 
-async function passLinkifyShowMessageToGopls(cfg: LanguageServerConfig, goplsConfig: any) {
+async function passLinkifyShowMessageToGopls(cfg: LanguageServerConfig, goplsConfig: ConfigurationObject): Promise<ConfigurationObject> {
 	goplsConfig = goplsConfig ?? {};
 
 	const goplsVersion = await getLocalGoplsVersion(cfg);
@@ -1025,6 +1050,29 @@ function createBenchmarkCodeLens(lens: vscode.CodeLens): vscode.CodeLens[] {
 	];
 }
 
+/**
+ * Builds the configuration object for the Go language server (gopls).
+ * This function locates gopls, validates it exists, and constructs the config needed to start it.
+ *
+ * Configuration includes:
+ * - Server executable path (from go.languageServerPath setting or auto-detected)
+ * - Server command-line flags (from go.languageServerFlags)
+ * - Environment variables for gopls process
+ * - Custom formatter (if go.formatTool is set to override gopls formatting)
+ * - Update check preferences (from go.toolsManagement.checkForUpdates)
+ * - Server version and modification time (for tracking updates)
+ *
+ * @param goConfig - VS Code workspace configuration for the Go extension
+ * @returns LanguageServerConfig object, with `enabled: false` if gopls is disabled or not found
+ *
+ * @example
+ * const goConfig = getGoConfig();
+ * const cfg = await buildLanguageServerConfig(goConfig);
+ * if (cfg.enabled) {
+ *   console.log(`Found gopls at: ${cfg.path}`);
+ *   const client = await buildLanguageClient(goCtx, cfg);
+ * }
+ */
 export async function buildLanguageServerConfig(
 	goConfig: vscode.WorkspaceConfiguration
 ): Promise<LanguageServerConfig> {

extension/src/util.ts

@@ -27,6 +27,16 @@ import {
 } from './utils/pathUtils';
 import { killProcessTree } from './utils/processUtils';
 
+/**
+ * Represents a command defined in the extension's package.json.
+ * Used for command palette and keybindings.
+ */
+export interface ExtensionCommand {
+	command: string;
+	title: string;
+	category?: string;
+}
+
 export class GoVersion {
 	public sv?: semver.SemVer;
 	// Go version tags are not following the strict semver format
@@ -298,14 +308,48 @@ function resolveToolsGopath(): string {
 	return toolsGopathForWorkspace;
 }
 
-// getBinPath returns the path to the tool.
+/**
+ * Returns the absolute path to a Go tool's executable.
+ * This is the primary function used throughout the extension to locate Go tools.
+ *
+ * Search order:
+ * 1. Alternate tools configured in go.alternateTools
+ * 2. GOBIN environment variable
+ * 3. Configured toolsGopath (go.toolsGopath setting)
+ * 4. Current workspace GOPATH
+ * 5. GOROOT/bin (for go, gofmt, godoc)
+ * 6. PATH environment variable
+ * 7. Default system locations (e.g., /usr/local/go/bin)
+ *
+ * @param tool - Name of the tool (e.g., 'gopls', 'dlv', 'staticcheck')
+ * @param useCache - Whether to use cached tool paths (default: true)
+ * @returns Absolute path to the tool executable, or just the tool name if not found
+ *
+ * @example
+ * const goplsPath = getBinPath('gopls'); // Returns '/Users/me/go/bin/gopls'
+ * const goPath = getBinPath('go'); // Returns '/usr/local/go/bin/go'
+ */
 export function getBinPath(tool: string, useCache = true): string {
 	const r = getBinPathWithExplanation(tool, useCache);
 	return r.binPath;
 }
 
-// getBinPathWithExplanation returns the path to the tool, and the explanation on why
-// the path was chosen. See getBinPathWithPreferredGopathGorootWithExplanation for details.
+/**
+ * Returns the absolute path to a Go tool's executable along with an explanation
+ * of where the path was found. Useful for diagnostics and troubleshooting.
+ *
+ * @param tool - Name of the tool (e.g., 'gopls', 'dlv', 'staticcheck')
+ * @param useCache - Whether to use cached tool paths (default: true)
+ * @param uri - Optional workspace URI for multi-root workspace support
+ * @returns Object containing the tool path and optional explanation
+ *   - binPath: Absolute path to the tool executable
+ *   - why: Optional explanation ('gobin', 'gopath', 'goroot', 'path', 'alternateTool', 'cached', 'default')
+ *
+ * @example
+ * const result = getBinPathWithExplanation('gopls');
+ * console.log(`Found gopls at ${result.binPath} (source: ${result.why})`);
+ * // Output: "Found gopls at /Users/me/go/bin/gopls (source: gobin)"
+ */
 export function getBinPathWithExplanation(
 	tool: string,
 	useCache = true,
@@ -332,6 +376,19 @@ export function getBinPathWithExplanation(
 	);
 }
 
+/**
+ * Serializes a VS Code document into the archive format expected by Go tools.
+ * This format is used to pass modified/unsaved file contents to tools like gopls and goimports.
+ *
+ * Format: `filename\nbytelength\ncontents`
+ *
+ * @param document - The VS Code text document to serialize
+ * @returns Serialized document in archive format
+ *
+ * @example
+ * const archive = getFileArchive(document);
+ * // Returns: "/path/to/file.go\n1234\npackage main..."
+ */
 export function getFileArchive(document: vscode.TextDocument): string {
 	const fileContents = document.getText();
 	return document.fileName + '\n' + Buffer.byteLength(fileContents, 'utf8') + '\n' + fileContents;
@@ -407,14 +464,18 @@ export function getModuleCache(): string | undefined {
 	}
 }
 
-export function getExtensionCommands(): any[] {
+/**
+ * Returns all commands defined in the extension's package.json.
+ * @returns Array of extension commands (excluding 'go.show.commands')
+ */
+export function getExtensionCommands(): ExtensionCommand[] {
 	const pkgJSON = vscode.extensions.getExtension(extensionId)?.packageJSON;
 	if (!pkgJSON.contributes || !pkgJSON.contributes.commands) {
 		return [];
 	}
-	const extensionCommands: any[] = vscode.extensions
+	const extensionCommands: ExtensionCommand[] = vscode.extensions
 		.getExtension(extensionId)
-		?.packageJSON.contributes.commands.filter((x: any) => x.command !== 'go.show.commands');
+		?.packageJSON.contributes.commands.filter((x: ExtensionCommand) => x.command !== 'go.show.commands');
 	return extensionCommands;
 }
 
@@ -530,7 +591,7 @@ export function runTool(
 	severity: string,
 	useStdErr: boolean,
 	toolName: string,
-	env: any,
+	env: NodeJS.ProcessEnv,
 	printUnexpectedOutput: boolean,
 	token?: vscode.CancellationToken
 ): Promise<ICheckResult[]> {
@@ -557,7 +618,7 @@ export function runTool(
 	return new Promise((resolve, reject) => {
 		p = cp.execFile(cmd, args, { env, cwd }, (err, stdout, stderr) => {
 			try {
-				if (err && (<any>err).code === 'ENOENT') {
+				if (err && (err as NodeJS.ErrnoException).code === 'ENOENT') {
 					// Since the tool is run on save which can be frequent
 					// we avoid sending explicit notification if tool is missing
 					console.log(`Cannot find ${toolName ? toolName : 'go'}`);
@@ -626,6 +687,28 @@ export function runTool(
 	});
 }
 
+/**
+ * Converts tool output errors into VS Code diagnostics and displays them in the Problems panel.
+ * This is the central function for surfacing errors from Go tools (gopls, staticcheck, golint, etc.)
+ * to the VS Code UI.
+ *
+ * Features:
+ * - Clears existing diagnostics before adding new ones
+ * - Maps error positions to VS Code ranges using token-based column calculation
+ * - Groups diagnostics by file for efficient display
+ * - Handles both open and closed files
+ * - Filters out diagnostics that overlap with gopls diagnostics (if gopls is enabled)
+ *
+ * @param goCtx - Go extension context for accessing configuration
+ * @param document - Optional document that triggered the check (for optimization)
+ * @param errors - Array of check results from Go tools
+ * @param diagnosticCollection - VS Code diagnostic collection to update (e.g., 'go-lint', 'go-vet')
+ * @param diagnosticSource - Optional source label for the diagnostics (e.g., 'staticcheck', 'golint')
+ *
+ * @example
+ * const errors = await runGoVet(document);
+ * handleDiagnosticErrors(goCtx, document, errors, vetDiagnosticCollection, 'go-vet');
+ */
 export function handleDiagnosticErrors(
 	goCtx: GoExtensionContext,
 	document: vscode.TextDocument | undefined,