save zsh builtin command descriptions to ts file vs json (#241967)

.eslint-ignore

@@ -13,6 +13,7 @@
 **/extensions/notebook-renderers/renderer-out/index.js
 **/extensions/simple-browser/media/index.js
 **/extensions/terminal-suggest/src/completions/upstream/**
+**/extensions/terminal-suggest/src/shell/zshBuiltinsCache.ts
 **/extensions/terminal-suggest/third_party/**
 **/extensions/typescript-language-features/test-workspace/**
 **/extensions/typescript-language-features/extension.webpack.config.js

build/filters.js

@@ -89,7 +89,7 @@ module.exports.indentationFilter = [
 	'!test/automation/out/**',
 	'!test/monaco/out/**',
 	'!test/smoke/out/**',
-	'!extensions/terminal-suggest/src/shell/zshBuiltinsCache.json',
+	'!extensions/terminal-suggest/src/shell/zshBuiltinsCache.ts',
 	'!extensions/terminal-suggest/src/completions/upstream/**',
 	'!extensions/typescript-language-features/test-workspace/**',
 	'!extensions/typescript-language-features/resources/walkthroughs/**',
@@ -194,6 +194,7 @@ module.exports.tsFormattingFilter = [
 	'!extensions/vscode-api-tests/testWorkspace2/**',
 	'!extensions/**/*.test.ts',
 	'!extensions/html-language-features/server/lib/jquery.d.ts',
+	'!extensions/terminal-suggest/src/shell/zshBuiltinsCache.ts',
 ];
 
 module.exports.eslintFilter = [

extensions/terminal-suggest/scripts/pullZshBuiltins.ts

@@ -248,14 +248,21 @@ const main = async () => {
 			console.log('\x1b[31mmissing short description for commands:\n' + missingShortDescription.join('\n') + '\x1b[0m');
 		}
 
-		// Save the cache to a JSON file
-		const cacheFilePath = path.join(__dirname, '../src/shell/zshBuiltinsCache.json');
+		// Save the cache to a TypeScript file
+		const cacheFilePath = path.join(__dirname, '../src/shell/zshBuiltinsCache.ts');
 		const cacheObject = Object.fromEntries(zshBuiltinsCommandDescriptionsCache);
-		await fs.writeFile(cacheFilePath, JSON.stringify(cacheObject, null, 2), 'utf8');
-		console.log('saved command descriptions cache to zshBuiltinsCache.json with ', Object.keys(cacheObject).length, 'entries');
+		const tsContent = `${copyright}\n\nexport const zshBuiltinsCommandDescriptionsCache = ${JSON.stringify(cacheObject, null, 2)} as const;`;
+		await fs.writeFile(cacheFilePath, tsContent, 'utf8');
+		console.log('saved command descriptions cache to zshBuiltinsCache.ts with ', Object.keys(cacheObject).length, 'entries');
 	} catch (error) {
 		console.error('Error:', error);
 	}
 };
 
+const copyright = `
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/`;
+
 main();

extensions/terminal-suggest/src/shell/zsh.ts

@@ -7,10 +7,9 @@ import * as vscode from 'vscode';
 import type { ICompletionResource } from '../types';
 import { execHelper, getAliasesHelper } from './common';
 import { type ExecOptionsWithStringEncoding } from 'node:child_process';
-import * as path from 'path';
-import * as fs from 'fs';
+import { zshBuiltinsCommandDescriptionsCache } from './zshBuiltinsCache';
 
-let zshBuiltinsCommandDescriptionsCache: Map<string, { shortDescription?: string; description: string; args: string | undefined }> | undefined;
+const commandDescriptionsCache: Map<string, { shortDescription?: string; description: string; args: string | undefined }> | undefined = parseCache(zshBuiltinsCommandDescriptionsCache);
 
 export async function getZshGlobals(options: ExecOptionsWithStringEncoding, existingCommands?: Set<string>): Promise<(string | ICompletionResource)[]> {
 	return [
@@ -39,22 +38,8 @@ async function getBuiltins(
 		});
 	}
 
-	if (!zshBuiltinsCommandDescriptionsCache) {
-		const cacheFilePath = path.join(__dirname, 'zshBuiltinsCache.json');
-		if (fs.existsSync(cacheFilePath)) {
-			try {
-				const cacheFileContent = fs.readFileSync(cacheFilePath, 'utf8');
-				const cacheObject = JSON.parse(cacheFileContent);
-				zshBuiltinsCommandDescriptionsCache = new Map(Object.entries(cacheObject));
-			} catch (e) {
-				console.error('Failed to load zsh builtins cache', e);
-			}
-		} else {
-			console.warn('zsh builtins cache not found');
-		}
-	}
 
-	for (const cmd of zshBuiltinsCommandDescriptionsCache?.keys() ?? []) {
+	for (const cmd of commandDescriptionsCache?.keys() ?? []) {
 		if (typeof cmd === 'string') {
 			try {
 				const result = getCommandDescription(cmd);
@@ -83,7 +68,7 @@ export function getCommandDescription(command: string): { documentation?: string
 	if (!zshBuiltinsCommandDescriptionsCache) {
 		return undefined;
 	}
-	const result = zshBuiltinsCommandDescriptionsCache?.get(command);
+	const result = commandDescriptionsCache?.get(command);
 	if (result?.shortDescription) {
 		return {
 			description: result.shortDescription,
@@ -98,3 +83,14 @@ export function getCommandDescription(command: string): { documentation?: string
 		};
 	}
 }
+
+function parseCache(cache: Object): Map<string, { shortDescription?: string; description: string; args: string | undefined }> | undefined {
+	if (!cache) {
+		return undefined;
+	}
+	const result = new Map<string, { shortDescription?: string; description: string; args: string | undefined }>();
+	for (const [key, value] of Object.entries(cache)) {
+		result.set(key, value);
+	}
+	return result;
+}

extensions/terminal-suggest/src/shell/zshBuiltinsCache.ts

@@ -1,4 +1,10 @@
-{
+
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+
+export const zshBuiltinsCommandDescriptionsCache = {
   ".": {
     "shortDescription": "Source a file",
     "description": ":   Read commands from *file* and execute them in the current shell environment.\n\n    If *file* does not contain a slash, or if **PATH_DIRS** is set, the shell looks in the components of **\\$path** to find the directory containing *file*. Files in the current directory are not read unless `**.**` appears somewhere in **\\$path**. If a file named `*file***.zwc**` is found, is newer than *file*, and is the compiled form (created with the **zcompile** builtin) of *file*, then commands are read from that file instead of *file*.\n\n    If any arguments *arg* are given, they become the positional parameters; the old positional parameters are restored when the *file* is done executing. However, if no arguments are given, the positional parameters remain those of the calling context, and no restoring is done.\n\n    If *file* was not found the return status is 127; if *file* was found but contained a syntax error the return status is 126; else the return status is the exit status of the last command executed.",
@@ -534,4 +540,4 @@
     "description": ":   See the section `The zsh/net/tcp Module` in *zshmodules(1).*",
     "args": "ztcp"
   }
-}
+} as const;