docs: Add missing documentation comments to multiple utility functions

.hintrc

@@ -0,0 +1,21 @@
+{
+  "extends": [
+    "development"
+  ],
+  "hints": {
+    "axe/text-alternatives": [
+      "default",
+      {
+        "image-alt": "off"
+      }
+    ],
+    "disown-opener": "off",
+    "axe/forms": [
+      "default",
+      {
+        "label": "off"
+      }
+    ],
+    "typescript-config/strict": "off"
+  }
+}

pre-download-build.js

@@ -45,17 +45,25 @@ for (const target of targets) {
   const downloadUrl = `https://github.com/TryGhost/node-sqlite3/releases/download/v5.1.7/sqlite3-v5.1.7-napi-v6-${
     target === "win32-arm64" ? "win32-ia32" : target
   }.tar.gz`;
-  execSync(`curl -L -o ${targetDir}/build.tar.gz ${downloadUrl}`);
+   // 检查下载文件是否存在
+   const filePath = `${targetDir}/build.tar.gz`;
+   if (fs.existsSync(filePath)) {
+     console.log(`[info] File already exists: ${filePath}`);
+   } else {
+     // 如果文件不存在，下载文件
+     console.log(`[info] Downloading ${target}...`);
+     execSync(`curl -L -o ${targetDir}/build.tar.gz ${downloadUrl}`);
+   }
   execSync(`cd ${targetDir} && tar -xvzf build.tar.gz`);
   fs.copyFileSync(
     `${targetDir}/build/Release/node_sqlite3.node`,
     `${targetDir}/node_sqlite3.node`,
   );
-  fs.unlinkSync(`${targetDir}/build.tar.gz`);
-  fs.rmSync(`${targetDir}/build`, {
-    recursive: true,
-    force: true,
-  });
+  // fs.unlinkSync(`${targetDir}/build.tar.gz`);
+  // fs.rmSync(`${targetDir}/build`, {
+  //   recursive: true,
+  //   force: true,
+  // });
 }
 
 console.log("[info] Downloading prebuilt lancedb...");

src/context.ts

@@ -2,19 +2,39 @@ import * as vscode from "vscode";
 
 let _context: vscode.ExtensionContext | undefined;
 
+/**
+ * 设置扩展上下文
+ *
+ * @param context 扩展上下文对象
+ */
 export function setExtensionContext(context: vscode.ExtensionContext) {
   _context = context;
 }
 
+/**
+ * 获取扩展程序的URI。
+ *
+ * @returns 返回扩展程序的URI。
+ */
 export function getExtensionUri() {
   return _context?.extensionUri!;
 }
 
 
+/**
+ * 获取扩展上下文对象
+ *
+ * @returns 扩展上下文对象
+ */
 export function getExtensionContext() {
   return _context!;
 }
 
+/**
+ * 移除扩展上下文
+ *
+ * 将扩展上下文 `_context` 设置为 `undefined`，以清除扩展上下文信息。
+ */
 export function removeExtensionContext() {
   _context = undefined;
 }

src/editor/editor-api/VSCodeAction.ts

@@ -10,53 +10,98 @@ import { defaultIgnoreFile } from "../util/ignore";
 export class VSCodeAction implements IdeAction {
 	git: GitAction = new GitAction();
 
+	/**
+	 * 执行命令
+	 *
+	 * @param command 命令字符串
+	 * @returns Promise<void> 无返回值
+	 */
 	async runCommand(command: string): Promise<void> {
+		// 如果有已打开的终端
 		if (vscode.window.terminals.length) {
+			// 显示第一个终端
 			vscode.window.terminals[0].show();
+			// 在终端中发送命令
 			vscode.window.terminals[0].sendText(command, false);
 		} else {
+			// 创建一个新的终端
 			const terminal = vscode.window.createTerminal();
+			// 显示新创建的终端
 			terminal.show();
+			// 在新创建的终端中发送命令
 			terminal.sendText(command, false);
 		}
 	}
 
 	//   getTerminalContents: [undefined, string];
+	/**
+	 * 获取终端内容
+	 *
+	 * @param commands 要选择的命令数量，默认为-1，表示选择所有内容
+	 * @returns 返回终端内容的Promise对象
+	 */
 	async getTerminalContents(commands: number = -1): Promise<string> {
+		// 读取剪贴板的内容到临时变量tempCopyBuffer
 		const tempCopyBuffer = await vscode.env.clipboard.readText();
+
+		// 如果commands小于0
 		if (commands < 0) {
+			// 执行命令选择终端中的所有内容
 			await vscode.commands.executeCommand(
 				"workbench.editor-api.terminal.selectAll"
 			);
 		} else {
+			// 遍历执行命令选择上一个命令的内容，循环次数为commands
 			for (let i = 0; i < commands; i++) {
 				await vscode.commands.executeCommand(
 					"workbench.editor-api.terminal.selectToPreviousCommand"
 				);
 			}
 		}
+
+		// 执行命令复制选中的终端内容
 		await vscode.commands.executeCommand(
 			"workbench.editor-api.terminal.copySelection"
 		);
+
+		// 执行命令清除选中的终端内容
 		await vscode.commands.executeCommand(
 			"workbench.editor-api.terminal.clearSelection"
 		);
+
+		// 读取剪贴板的内容到terminalContents变量
 		const terminalContents = await vscode.env.clipboard.readText();
+
+		// 将临时变量tempCopyBuffer的内容写回剪贴板
 		await vscode.env.clipboard.writeText(tempCopyBuffer);
 
+		// 如果临时变量tempCopyBuffer与终端内容terminalContents相同
 		if (tempCopyBuffer === terminalContents) {
-			// This means there is no terminal open to select text from
+			// 这意味着没有打开的终端可以从中选择文本
 			return "";
 		}
+
+		// 返回终端内容
 		return terminalContents;
 	}
 
+	/**
+	 * 获取工作区目录列表
+	 *
+	 * @returns 返回工作区目录的路径数组，若获取失败则返回空数组
+	 */
 	getWorkspaceDirectories(): string[] {
 		return (vscode.workspace.workspaceFolders?.map((folder) => folder.uri.fsPath) || []);
 	}
 
 	private static MAX_BYTES = 100000;
 
+	/**
+	 * 获取文件路径的绝对路径
+	 *
+	 * @param filepath 文件路径
+	 * @returns 返回绝对路径字符串
+	 */
 	getAbsolutePath(filepath: string): string {
 		const workspaceDirectories = this.getWorkspaceDirectories();
 		if (!path.isAbsolute(filepath) && workspaceDirectories.length === 1) {
@@ -66,50 +111,81 @@ export class VSCodeAction implements IdeAction {
 		}
 	}
 
+	/**
+	 * 异步读取文件内容
+	 *
+	 * @param filepath 文件路径
+	 * @returns 返回文件内容的Promise对象
+	 */
 	async readFile(filepath: string): Promise<string> {
 		try {
+			// 获取文件的绝对路径
 			filepath = this.getAbsolutePath(filepath);
+			// 将文件路径转换为 URI
 			const uri = this.uriFromFilePath(filepath);
 
-			// Check first whether it's an open document
+			// 首先检查是否是已打开的文档
 			const openTextDocument = vscode.workspace.textDocuments.find(
 				(doc) => doc.uri.fsPath === uri.fsPath,
 			);
 			if (openTextDocument !== undefined) {
+				// 如果是已打开的文档，直接返回文档内容
 				return openTextDocument.getText();
 			}
 
+			// 获取文件状态信息
 			const fileStats = await vscode.workspace.fs.stat(
 				this.uriFromFilePath(filepath),
 			);
+			// 如果文件大小超过最大限制，返回空字符串
 			if (fileStats.size > 10 * VSCodeAction.MAX_BYTES) {
 				return "";
 			}
 
+			// 读取文件内容
 			const bytes = await vscode.workspace.fs.readFile(uri);
 
-			// Truncate the buffer to the first MAX_BYTES
+			// 截取缓冲区的前 MAX_BYTES 字节
 			const truncatedBytes = bytes.slice(0, VSCodeAction.MAX_BYTES);
+			// 将字节解码为字符串
 			const contents = new TextDecoder().decode(truncatedBytes);
+			// 返回文件内容
 			return contents;
 		} catch {
+			// 如果发生异常，返回空字符串
 			return "";
 		}
 	}
 
+	/**
+	 * 根据文件路径获取vscode.Uri对象
+	 *
+	 * @param filepath 文件路径
+	 * @returns 返回一个vscode.Uri对象
+	 */
 	uriFromFilePath(filepath: string): vscode.Uri {
+		// 如果当前环境是远程环境
 		if (vscode.env.remoteName) {
+			// 如果当前环境是Windows本地环境但不是远程环境
 			if (this.isWindowsLocalButNotRemote()) {
+				// 将文件路径从Windows格式转换为POSIX格式
 				filepath = this.windowsToPosix(filepath);
 			}
+			// 根据远程环境名称和文件路径构造VSCode的URI对象
 			return vscode.Uri.parse(
 				`vscode-remote://${vscode.env.remoteName}${filepath}`,
 			);
 		} else {
+			// 如果当前环境不是远程环境，则构造本地文件的VSCode URI对象
 			return vscode.Uri.file(filepath);
 		}
 	}
 
+	/**
+	 * 判断当前环境是否为 Windows 本地环境且非远程环境。
+	 *
+	 * @returns 返回一个布尔值，表示当前环境是否为 Windows 本地环境且非远程环境。
+	 */
 	isWindowsLocalButNotRemote(): boolean {
 		return (
 			vscode.env.remoteName !== undefined &&
@@ -120,6 +196,11 @@ export class VSCodeAction implements IdeAction {
 		);
 	}
 
+	/**
+	 * 获取路径分隔符
+	 *
+	 * @returns 如果当前环境是本地Windows环境但不是远程Windows环境，返回 "/"；否则返回 path.sep
+	 */
 	getPathSep(): string {
 		return this.isWindowsLocalButNotRemote() ? "/" : path.sep;
 	}
@@ -133,10 +214,22 @@ export class VSCodeAction implements IdeAction {
 		return posixPath;
 	}
 
+	/**
+	 * 获取指定目录下的分支信息
+	 *
+	 * @param dir 指定的目录路径
+	 * @returns 返回分支信息的字符串
+	 */
 	async getBranch(dir: string): Promise<string> {
 		return this.getBranchForUri(vscode.Uri.file(dir));
 	}
 
+	/**
+	 * 根据目录URI获取分支名
+	 *
+	 * @param forDirectory 目录URI
+	 * @returns 分支名，如果获取失败则返回"NONE"
+	 */
 	async getBranchForUri(forDirectory: vscode.Uri) {
 		let repo = await this.git.getRepo(forDirectory);
 		if (repo?.state?.HEAD?.name === undefined) {
@@ -153,32 +246,65 @@ export class VSCodeAction implements IdeAction {
 		return repo?.state?.HEAD?.name || "NONE";
 	}
 
+	/**
+	 * 获取指定目录下所有文件的最后修改时间
+	 *
+	 * @param directory 目录路径
+	 * @returns 返回文件路径到最后修改时间的映射对象
+	 */
 	async getStats(directory: string): Promise<{ [path: string]: number }> {
+		// 获取工作区第一个文件夹的 URI scheme
 		const scheme = vscode.workspace.workspaceFolders?.[0].uri.scheme;
+
+		// 列出目录中的文件列表
 		const files = await this.listWorkspaceContents(directory);
+
+		// 创建一个对象，用于存储每个文件的最后修改时间
 		const pathToLastModified: { [path: string]: number } = {};
+
 		await Promise.all(
 			files.map(async (file) => {
+				// 获取文件的统计信息
 				let stat = await vscode.workspace.fs.stat(this.uriFromFilePath(file));
+				// 将文件路径和最后修改时间存入对象中
 				pathToLastModified[file] = stat.mtime;
 			}),
 		);
 
+		// 返回包含文件最后修改时间的对象
 		return pathToLastModified;
 	}
 
+	/**
+	 * 列出工作区的内容
+	 *
+	 * @param directory 目录路径，可选
+	 * @returns 返回工作区内容的文件路径数组
+	 */
 	async listWorkspaceContents(directory?: string): Promise<string[]> {
+		// 如果提供了目录参数
 		if (directory) {
+			// 调用获取目录内容的函数，并返回结果
 			return await this.getDirectoryContents(directory, true);
 		} else {
+			// 获取工作区所有目录
 			const contents = await Promise.all(
 				this.getWorkspaceDirectories()
+					// 对每个目录调用获取目录内容的函数，并返回结果的数组
 					.map((dir) => this.getDirectoryContents(dir, true)),
 			);
+			// 将所有目录的内容合并成一个数组并返回
 			return contents.flat();
 		}
 	}
 
+	/**
+	 * 异步获取目录内容
+	 *
+	 * @param directory 目录路径
+	 * @param recursive 是否递归搜索子目录
+	 * @returns 目录内容（文件路径数组）
+	 */
 	async getDirectoryContents(
 		directory: string,
 		recursive: boolean,
@@ -213,6 +339,12 @@ export class VSCodeAction implements IdeAction {
 		return allFiles;
 	}
 
+	/**
+	 * 获取仓库名称
+	 *
+	 * @param dir 仓库目录
+	 * @returns 仓库名称，若无法获取则返回 undefined
+	 */
 	getRepoName(dir: string): Promise<string | undefined> {
 		return this.git.getRepoName(vscode.Uri.file(dir));
 	}