add builtin fish arg/description/documentation to suggestion (#243271)

.eslint-ignore

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

build/filters.js

@@ -57,6 +57,7 @@ module.exports.unicodeFilter = [
 	'!extensions/**/out/**',
 	'!extensions/**/snippets/**',
 	'!extensions/**/colorize-fixtures/**',
+	'!extensions/terminal-suggest/src/shell/fishBuiltinsCache.ts',
 
 	'!src/vs/base/browser/dompurify/**',
 	'!src/vs/workbench/services/keybinding/browser/keyboardLayouts/**',
@@ -90,6 +91,7 @@ module.exports.indentationFilter = [
 	'!test/monaco/out/**',
 	'!test/smoke/out/**',
 	'!extensions/terminal-suggest/src/shell/zshBuiltinsCache.ts',
+	'!extensions/terminal-suggest/src/shell/fishBuiltinsCache.ts',
 	'!extensions/terminal-suggest/src/completions/upstream/**',
 	'!extensions/typescript-language-features/test-workspace/**',
 	'!extensions/typescript-language-features/resources/walkthroughs/**',
@@ -195,6 +197,7 @@ module.exports.tsFormattingFilter = [
 	'!extensions/**/*.test.ts',
 	'!extensions/html-language-features/server/lib/jquery.d.ts',
 	'!extensions/terminal-suggest/src/shell/zshBuiltinsCache.ts',
+	'!extensions/terminal-suggest/src/shell/fishBuiltinsCache.ts',
 ];
 
 module.exports.eslintFilter = [

extensions/terminal-suggest/ThirdPartyNotices.txt

@@ -28,5 +28,3 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
-
-

extensions/terminal-suggest/cgmanifest.json

@@ -82,6 +82,63 @@
 				"SOFTWARE."
 			],
 			"version": "1.1.2"
+		},
+		{
+			"component": {
+				"type": "git",
+				"git": {
+					"repositoryUrl": "https://github.com/zsh-users/zsh",
+					"commitHash": "435cb1b748ce1f2f5c38edc1d64f4ee2424f9b3a"
+				}
+			},
+			"version": "5.9",
+			"licenseDetail": [
+				"Unless otherwise noted in the header of specific files, files in this distribution have the licence shown below.",
+				"",
+				"However, note that certain shell functions are licensed under versions of the GNU General Public Licence.  Anyone distributing the shell as a binary including those files needs to take account of this.  Search shell functions for \"Copyright\" for specific copyright information. None of the core functions are affected by this, so those files may simply be omitted.",
+				"",
+				"--",
+				"",
+				"The Z Shell is copyright (c) 1992-2017 Paul Falstad, Richard Coleman, Zoltán Hidvégi, Andrew Main, Peter Stephenson, Sven Wischnowsky, and others.  All rights reserved.  Individual authors, whether or not specifically named, retain copyright in all changes; in what follows, they are referred to as `the Zsh Development Group'.  This is for convenience only and this body has no legal status.  The Z shell is distributed under the following licence; any provisions made in individual files take precedence.",
+				"",
+				"Permission is hereby granted, without written agreement and without licence or royalty fees, to use, copy, modify, and distribute this software and to distribute modified versions of this software for any purpose, provided that the above copyright notice and the following two paragraphs appear in all copies of this software.",
+				"",
+				"In no event shall the Zsh Development Group be liable to any party for direct, indirect, special, incidental, or consequential damages arising out of the use of this software and its documentation, even if the Zsh Development Group have been advised of the possibility of such damage.",
+				"",
+				"The Zsh Development Group specifically disclaim any warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose.  The software provided hereunder is on an \"as is\" basis, and the Zsh Development Group have no obligation to provide maintenance, support, updates, enhancements, or modifications."
+			]
+		},
+		{
+			"component": {
+				"type": "git",
+				"git": {
+					"repositoryUrl": "https://github.com/fish-shell/fish-shell",
+					"commitHash": "6627d403d33b4e74b49aa4db2a4f17709628cdc8"
+				}
+			},
+			"version": "3.7.1",
+			"licenseDetail": [
+				"Fish is a smart and user-friendly command line shell.",
+				"",
+				"Copyright (C) 2005-2009 Axel Liljencrantz",
+				"Copyright (C) 2009- fish-shell contributors",
+				"",
+				"fish is free software.",
+				"",
+				"Most of fish is licensed under the GNU General Public License version 2, and",
+				"you can redistribute it and/or modify it under the terms of the GNU GPL as",
+				"published by the Free Software Foundation.",
+				"",
+				"fish also includes software licensed under the Python Software Foundation License version 2, the MIT",
+				"license, and the GNU Library General Public License version 2.",
+				"",
+				"Full licensing information is contained in doc_src/license.rst.",
+				"",
+				"This program is distributed in the hope that it will be useful, but WITHOUT",
+				"ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or",
+				"FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for",
+				"more details."
+			]
 		}
 	],
 	"version": 1

extensions/terminal-suggest/package.json

@@ -21,7 +21,8 @@
   "scripts": {
     "compile": "npx gulp compile-extension:terminal-suggest",
     "watch": "npx gulp watch-extension:terminal-suggest",
-    "pull-zshbuiltins": "ts-node ./scripts/pullZshBuiltins.ts"
+    "pull-zshbuiltins": "ts-node ./scripts/pullZshBuiltins.ts",
+    "pull-fishbuiltins": "ts-node ./scripts/pullFishBuiltins.ts"
   },
   "main": "./out/terminalSuggestMain",
   "activationEvents": [

extensions/terminal-suggest/scripts/pullFishBuiltins.ts

@@ -0,0 +1,260 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { cleanupText, checkWindows, execAsync, copyright } from './terminalScriptHelpers';
+
+checkWindows();
+
+interface ICommandDetails {
+	description: string;
+	args: string | undefined;
+	shortDescription?: string;
+}
+
+let fishBuiltinsCommandDescriptionsCache = new Map<string, ICommandDetails>();
+
+// Fallback descriptions for commands that don't return proper help information
+const fallbackDescriptions: Record<string, ICommandDetails> = {
+	'[': {
+		shortDescription: 'Test if a statement is true',
+		description: 'Evaluate an expression and return a status of true (0) or false (non-zero). Unlike the `test` command, the `[` command requires a closing `]`.',
+		args: 'EXPRESSION ]'
+	},
+	'break': {
+		shortDescription: 'Exit the current loop',
+		description: 'Terminate the execution of the nearest enclosing `while` or `for` loop and proceed with the next command after the loop.',
+		args: undefined
+	},
+	'breakpoint': {
+		shortDescription: 'Launch debug mode',
+		description: 'Pause execution and launch an interactive debug prompt. This is useful for inspecting the state of a script at a specific point.',
+		args: undefined
+	},
+	'case': {
+		shortDescription: 'Match a value against patterns',
+		description: 'Within a `switch` block, the `case` command specifies patterns to match against the given value, executing the associated block if a match is found.',
+		args: 'PATTERN...'
+	},
+	'continue': {
+		shortDescription: 'Skip to the next iteration of a loop',
+		description: 'Within a `while` or `for` loop, `continue` skips the remaining commands in the current iteration and proceeds to the next iteration of the loop.',
+		args: undefined
+	},
+	'else': {
+		shortDescription: 'Execute commands if the previous condition was false',
+		description: 'In an `if` block, the `else` section contains commands that execute if none of the preceding `if` or `else if` conditions were true.',
+		args: undefined
+	},
+	'end': {
+		shortDescription: 'Terminate a block of code',
+		description: 'Conclude a block of code initiated by constructs like `if`, `switch`, `while`, `for`, or `function`.',
+		args: undefined
+	},
+	'eval': {
+		shortDescription: 'Execute arguments as a command',
+		description: 'Concatenate all arguments into a single command and execute it. This allows for dynamic construction and execution of commands.',
+		args: 'COMMAND...'
+	},
+	'false': {
+		shortDescription: 'Return an unsuccessful result',
+		description: 'A command that returns a non-zero exit status, indicating failure. It is often used in scripts to represent a false condition.',
+		args: undefined
+	},
+	'realpath': {
+		shortDescription: 'Resolve and print the absolute path',
+		description: 'Convert each provided path to its absolute, canonical form by resolving symbolic links and relative path components.',
+		args: 'PATH...'
+	},
+	':': {
+		shortDescription: 'No operation command',
+		description: 'The `:` command is a no-op (no operation) command that returns a successful (zero) exit status. It can be used as a placeholder in scripts where a command is syntactically required but no action is desired.',
+		args: undefined
+	},
+	'test': {
+		shortDescription: 'Evaluate conditional expressions',
+		description: 'The `test` command evaluates conditional expressions and sets the exit status to 0 if the expression is true, and 1 if it is false. It supports various operators to evaluate expressions related to strings, numbers, and file attributes.',
+		args: 'EXPRESSION'
+	},
+	'true': {
+		shortDescription: 'Return a successful result',
+		description: 'The `true` command always returns a successful (zero) exit status. It is often used in scripts and conditional statements where an unconditional success result is needed.',
+		args: undefined
+	},
+	'printf': {
+		shortDescription: 'Display formatted text',
+		description: 'The `printf` command formats and prints text according to a specified format string. Unlike `echo`, `printf` does not append a newline unless explicitly included in the format.',
+		args: 'FORMAT [ARGUMENT...]'
+	}
+};
+
+
+async function createCommandDescriptionsCache(): Promise<void> {
+	const cachedCommandDescriptions: Map<string, { shortDescription?: string; description: string; args: string | undefined }> = new Map();
+
+	try {
+		// Get list of all builtins
+		const builtinsOutput = await execAsync('fish -c "builtin -n"').then(r => r.stdout.trim());
+		const builtins = builtinsOutput.split('\n');
+
+		console.log(`Found ${builtins.length} Fish builtin commands`);
+
+		for (const cmd of builtins) {
+			try {
+				// Get help info for each builtin
+				const helpOutput = await execAsync(`fish -c "${cmd} --help 2>&1"`).then(r => r.stdout);
+				let set = false;
+				if (helpOutput && !helpOutput.includes('No help for function') && !helpOutput.includes('See the web documentation')) {
+					const cleanHelpText = cleanupText(helpOutput);
+
+					// Split the text into lines to process
+					const lines = cleanHelpText.split('\n');
+
+
+					// Extract the short description, args, and full description
+					const { shortDescription, args, description } = extractHelpContent(cmd, lines);
+
+					cachedCommandDescriptions.set(cmd, {
+						shortDescription,
+						description,
+						args
+					});
+					set = description !== '';
+				}
+				if (!set) {
+					// Use fallback descriptions for commands that don't return proper help
+					if (fallbackDescriptions[cmd]) {
+						console.info(`Using fallback description for ${cmd}`);
+						cachedCommandDescriptions.set(cmd, fallbackDescriptions[cmd]);
+					} else {
+						console.info(`No fallback description exists for ${cmd}`);
+					}
+				}
+			} catch {
+				// Use fallback descriptions for commands that throw an error
+				if (fallbackDescriptions[cmd]) {
+					console.info('Using fallback description for', cmd);
+					cachedCommandDescriptions.set(cmd, fallbackDescriptions[cmd]);
+				} else {
+					console.info(`Error getting help for ${cmd}`);
+				}
+			}
+		}
+	} catch (e) {
+		console.error('Error creating Fish builtins cache:', e);
+		process.exit(1);
+	}
+
+	fishBuiltinsCommandDescriptionsCache = cachedCommandDescriptions;
+}
+
+/**
+ * Extracts short description, args, and full description from help text lines
+ */
+function extractHelpContent(cmd: string, lines: string[]): { shortDescription: string; args: string | undefined; description: string } {
+	let shortDescription = '';
+	let args: string | undefined;
+	let description = '';
+
+	// Skip the first line (usually just command name and basic usage)
+	let i = 1;
+
+	// Skip any leading empty lines
+	while (i < lines.length && lines[i].trim().length === 0) {
+		i++;
+	}
+
+	// The next non-empty line after the command name is typically
+	// either the short description or additional usage info
+	const startLine = i;
+
+	// Find where the short description starts
+	if (i < lines.length) {
+		// First, check if the line has a command prefix and remove it
+		let firstContentLine = lines[i].trim();
+		const cmdPrefixRegex = new RegExp(`^${cmd}\\s*-\\s*`, 'i');
+		firstContentLine = firstContentLine.replace(cmdPrefixRegex, '');
+
+		// First non-empty line is the short description
+		shortDescription = firstContentLine;
+		i++;
+
+		// Next non-empty line (after short description) is typically args
+		while (i < lines.length && lines[i].trim().length === 0) {
+			i++;
+		}
+
+		if (i < lines.length) {
+			// Found a line after the short description - that's our args
+			args = lines[i].trim();
+			i++;
+		}
+	}
+
+	// Find the DESCRIPTION marker which marks the end of args section
+	let descriptionIndex = -1;
+	for (let j = i; j < lines.length; j++) {
+		if (lines[j].trim() === 'DESCRIPTION') {
+			descriptionIndex = j;
+			break;
+		}
+	}
+
+	// If DESCRIPTION marker is found, consider everything between i and descriptionIndex as part of args
+	if (descriptionIndex > i) {
+		// Combine lines from i up to (but not including) descriptionIndex
+		const additionalArgs = lines.slice(i, descriptionIndex).join('\n').trim();
+		if (additionalArgs) {
+			args = args ? `${args}\n${additionalArgs}` : additionalArgs;
+		}
+		i = descriptionIndex + 1; // Move past the DESCRIPTION line
+	}
+
+	// The rest is the full description (skipping any empty lines after args)
+	while (i < lines.length && lines[i].trim().length === 0) {
+		i++;
+	}
+
+	// Combine the remaining lines into the full description
+	description = lines.slice(Math.max(i, startLine)).join('\n').trim();
+
+	// If description is empty, use the short description
+	if (!description && shortDescription) {
+		description = shortDescription;
+	}
+
+	// Extract just the first sentence for short description
+	const firstPeriodIndex = shortDescription.indexOf('.');
+	if (firstPeriodIndex > 0) {
+		shortDescription = shortDescription.substring(0, firstPeriodIndex + 1).trim();
+	} else if (shortDescription.length > 100) {
+		shortDescription = shortDescription.substring(0, 100) + '...';
+	}
+
+	return {
+		shortDescription,
+		args,
+		description
+	};
+}
+
+const main = async () => {
+	try {
+		await createCommandDescriptionsCache();
+		console.log('Created Fish command descriptions cache with', fishBuiltinsCommandDescriptionsCache.size, 'entries');
+
+		// Save the cache to a TypeScript file
+		const cacheFilePath = path.join(__dirname, '../src/shell/fishBuiltinsCache.ts');
+		const cacheObject = Object.fromEntries(fishBuiltinsCommandDescriptionsCache);
+		const tsContent = `${copyright}\n\nexport const fishBuiltinsCommandDescriptionsCache = ${JSON.stringify(cacheObject, null, 2)} as const;`;
+		await fs.writeFile(cacheFilePath, tsContent, 'utf8');
+		console.log('Saved Fish command descriptions cache to fishBuiltinsCache.ts with', Object.keys(cacheObject).length, 'entries');
+	} catch (error) {
+		console.error('Error:', error);
+	}
+};
+
+main();

extensions/terminal-suggest/scripts/pullZshBuiltins.ts

@@ -3,16 +3,11 @@
  *  Licensed under the MIT License. See License.txt in the project root for license information.
  *--------------------------------------------------------------------------------------------*/
 
-import { exec } from 'child_process';
-import { promisify } from 'util';
 import * as fs from 'fs/promises';
 import * as path from 'path';
-import { platform } from 'os';
+import { checkWindows, execAsync, copyright } from './terminalScriptHelpers';
 
-if (platform() === 'win32') {
+checkWindows();
-	console.error('\x1b[31mThis command is not supported on Windows\x1b[0m');
-	process.exit(1);
-}
 
 const latestZshVersion = 5.9;
 
@@ -126,14 +121,14 @@ const shortDescriptions: Map<string, string> = new Map([
 	['ztcp', 'Manipulate TCP sockets'],
 ]);
 
-const execAsync = promisify(exec);
-
 interface ICommandDetails {
 	description: string;
 	args: string | undefined;
 	shortDescription?: string;
 }
+
 let zshBuiltinsCommandDescriptionsCache = new Map<string, ICommandDetails>();
+
 async function createCommandDescriptionsCache(): Promise<void> {
 	const cachedCommandDescriptions: Map<string, { shortDescription?: string; description: string; args: string | undefined }> = new Map();
 	let output = '';
@@ -259,10 +254,4 @@ const main = async () => {
 	}
 };
 
-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/scripts/terminalScriptHelpers.ts

@@ -0,0 +1,51 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+
+import { platform } from 'os';
+import { exec } from 'child_process';
+import { promisify } from 'util';
+
+export const execAsync = promisify(exec);
+
+/**
+ * Cleans up text from terminal control sequences and formatting artifacts
+ */
+export function cleanupText(text: string): string {
+	// Remove ANSI escape codes
+	let cleanedText = text.replace(/\x1b\[\d+m/g, '');
+
+	// Remove backspace sequences (like a\bb which tries to print a, move back, print b)
+	// This regex looks for a character followed by a backspace and another character
+	const backspaceRegex = /.\x08./g;
+	while (backspaceRegex.test(cleanedText)) {
+		cleanedText = cleanedText.replace(backspaceRegex, match => match.charAt(2));
+	}
+
+	// Remove any remaining backspaces and their preceding characters
+	cleanedText = cleanedText.replace(/.\x08/g, '');
+
+	// Remove underscores that are used for formatting in some fish help output
+	cleanedText = cleanedText.replace(/_\b/g, '');
+
+	return cleanedText;
+}
+
+/**
+ * Copyright notice for generated files
+ */
+export const copyright = `/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/`;
+
+/**
+ * Checks if the script is running on Windows and exits if so
+ */
+export function checkWindows(): void {
+	if (platform() === 'win32') {
+		console.error('\x1b[31mThis command is not supported on Windows\x1b[0m');
+		process.exit(1);
+	}
+}

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

@@ -3,21 +3,87 @@
  *  Licensed under the MIT License. See License.txt in the project root for license information.
  *--------------------------------------------------------------------------------------------*/
 
+import * as vscode from 'vscode';
 import type { ICompletionResource } from '../types';
-import { execHelper, getAliasesHelper } from './common';
+import { getAliasesHelper } from './common';
 import { type ExecOptionsWithStringEncoding } from 'node:child_process';
+import { fishBuiltinsCommandDescriptionsCache } from './fishBuiltinsCache';
+
+const commandDescriptionsCache: Map<string, { shortDescription?: string; description: string; args: string | undefined }> | undefined = parseCache(fishBuiltinsCommandDescriptionsCache);
 
 export async function getFishGlobals(options: ExecOptionsWithStringEncoding, existingCommands?: Set<string>): Promise<(string | ICompletionResource)[]> {
 	return [
 		...await getAliases(options),
-		...await getBuiltins(options, existingCommands),
+		...await getBuiltins(options),
 	];
 }
 
-async function getBuiltins(options: ExecOptionsWithStringEncoding, existingCommands?: Set<string>): Promise<string[]> {
+async function getBuiltins(options: ExecOptionsWithStringEncoding): Promise<(string | ICompletionResource)[]> {
-	const compgenOutput = await execHelper('functions -n', options);
+	const completions: ICompletionResource[] = [];
-	const filter = (cmd: string) => cmd && !existingCommands?.has(cmd);
+
-	return compgenOutput.split(', ').filter(filter);
+	// Use the cache directly for all commands
+	for (const cmd of [...commandDescriptionsCache!.keys()]) {
+		try {
+			const result = getCommandDescription(cmd);
+			if (result) {
+				completions.push({
+					label: { label: cmd, description: result.description },
+					detail: result.args,
+					documentation: new vscode.MarkdownString(result.documentation),
+					kind: vscode.TerminalCompletionItemKind.Method
+				});
+			} else {
+				console.warn(`Fish command "${cmd}" not found in cache.`);
+				completions.push({
+					label: cmd,
+					kind: vscode.TerminalCompletionItemKind.Method
+				});
+			}
+		} catch (e) {
+			// Ignore errors
+			completions.push({
+				label: cmd,
+				kind: vscode.TerminalCompletionItemKind.Method
+			});
+		}
+	}
+
+	return completions;
+}
+
+export function getCommandDescription(command: string): { documentation?: string; description?: string; args?: string | undefined } | undefined {
+	if (!commandDescriptionsCache) {
+		return undefined;
+	}
+	const result = commandDescriptionsCache.get(command);
+	if (!result) {
+		return undefined;
+	}
+
+	if (result.shortDescription) {
+		return {
+			description: result.shortDescription,
+			args: result.args,
+			documentation: result.description
+		};
+	} else {
+		return {
+			description: result.description,
+			args: result.args,
+			documentation: result.description
+		};
+	}
+}
+
+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;
 }
 
 async function getAliases(options: ExecOptionsWithStringEncoding): Promise<ICompletionResource[]> {