\n \n fish-lsp\n \n
\n\n ![\"GitHub](\"https://img.shields.io/github/actions/workflow/status/ndonfris/fish-lsp/ci.yml?branch=master&labelColor=%23181939\")
\n ![\"License\"](\"https://img.shields.io/github/license/ndonfris/fish-lsp?&labelColor=%23181939&color=b88af3\")
\n ![\"Github](\"https://img.shields.io/github/created-at/ndonfris/fish-lsp?logo=%234e6cfa&label=created&labelColor=%23181939&color=%236198f5\")
\n ![\"NPM](\"https://img.shields.io/npm/dw/fish-lsp?logoColor=%235f5fd7&labelColor=%23181939&color=%235f5fd7\")
\n
\n \n \n \n \n \n \n \n \n >= v0.8.x)\n\n\n\n\n\n\n###### :package: Default Values:
\n\n\n```fish\n# $fish_lsp_enabled_handlersfish-lsp env --show-default\n\n\n# Enables the fish-lsp handlers. By default, all stable handlers are enabled.\n# (Options: 'complete', 'hover', 'rename', 'definition', 'implementation', \n# 'reference', 'logger', 'formatting', 'formatRange', \n# 'typeFormatting', 'codeAction', 'codeLens', 'folding', \n# 'selectionRange', 'signature', 'executeCommand', 'inlayHint', \n# 'highlight', 'diagnostic', 'popups', 'semanticTokens')\n# (Default: [])\nset -gx fish_lsp_enabled_handlers \n\n# $fish_lsp_disabled_handlers \n# Disables the fish-lsp handlers. By default, non-stable handlers are disabled.\n# (Options: 'complete', 'hover', 'rename', 'definition', 'implementation', \n# 'reference', 'logger', 'formatting', 'formatRange', \n# 'typeFormatting', 'codeAction', 'codeLens', 'folding', \n# 'selectionRange', 'signature', 'executeCommand', 'inlayHint', \n# 'highlight', 'diagnostic', 'popups', 'semanticTokens')\n# (Default: [])\nset -gx fish_lsp_disabled_handlers \n\n# $fish_lsp_commit_characters \n# Array of the completion expansion characters.\n# Single letter values only.\n# Commit characters are used to select completion items, as shortcuts.\n# (Example Options: '.', ',', ';', ':', '(', ')', '[', ']', '{', '}', '<', \n# '>', ''', '\"', '=', '+', '-', '/', '\\', '|', '&', '%', \n# '$', '#', '@', '!', '?', '*', '^', '`', '~', '\\t', ' ')\n# (Default: ['\\t', ';', ' '])\nset -gx fish_lsp_commit_characters '\\t' ';' ' '\n\n# $fish_lsp_log_file \n# A path to the fish-lsp's logging file. Empty string disables logging.\n# (Example Options: '/tmp/fish_lsp.log', '~/path/to/fish_lsp/logs.txt')\n# (Default: '')\nset -gx fish_lsp_log_file ''\n\n# $fish_lsp_log_level \n# The logging severity level for displaying messages in the log file.\n# (Options: 'debug', 'info', 'warning', 'error', 'log')\n# (Default: '')\nset -gx fish_lsp_log_level ''\n\n# $fish_lsp_all_indexed_paths \n# The fish file paths to include in the fish-lsp's startup indexing, as workspaces.\n# Order matters (usually place `$__fish_config_dir` before `$__fish_data_dir`).\n# (Example Options: '$HOME/.config/fish', '/usr/share/fish', \n# '$__fish_config_dir', '$__fish_data_dir')\n# (Default: ['$__fish_config_dir', '$__fish_data_dir'])\nset -gx fish_lsp_all_indexed_paths \"$__fish_config_dir\" \"$__fish_data_dir\"\n\n# $fish_lsp_modifiable_paths \n# The fish file paths, for workspaces where global symbols can be renamed by the user.\n# (Example Options: '/usr/share/fish', '$HOME/.config/fish', \n# '$__fish_data_dir', '$__fish_config_dir')\n# (Default: ['$__fish_config_dir'])\nset -gx fish_lsp_modifiable_paths \"$__fish_config_dir\"\n\n# $fish_lsp_diagnostic_disable_error_codes \n# The diagnostics error codes to disable from the fish-lsp's diagnostics.\n# (Options: 1001, 1002, 1003, 1004, 1005, 2001, 2002, 2003, 2004, 3001, 3002, \n# 3003, 4001, 4002, 4003, 4004, 4005, 4006, 4007, 4008, 5001, 5555, \n# 6001, 7001, 8001, 9999)\n# (Default: [])\nset -gx fish_lsp_diagnostic_disable_error_codes \n\n# $fish_lsp_max_diagnostics \n# The maximum number of diagnostics to return per file.\n# Using value `0` means unlimited diagnostics.\n# To entirely disable diagnostics use `fish_lsp_disabled_handlers`\n# (Example Options: 0, 10, 25, 50, 100, 250)\n# (Default: 0)\nset -gx fish_lsp_max_diagnostics 0\n\n# $fish_lsp_enable_experimental_diagnostics \n# Enables the experimental diagnostics feature, using `fish --no-execute`.\n# This feature will enable the diagnostic error code 9999 (disabled by default).\n# (Options: 'true', 'false')\n# (Default: 'false')\nset -gx fish_lsp_enable_experimental_diagnostics false\n\n# $fish_lsp_strict_conditional_command_warnings \n# Diagnostic `3002` includes/excludes conditionally chained commands to explicitly check existence.\n# ENABLED EXAMPLE: `command -q ls && command ls || echo 'no ls'`\n# DISABLED EXAMPLE: `command ls || echo 'no ls'`\n# (Options: 'true', 'false')\n# (Default: 'false')\nset -gx fish_lsp_strict_conditional_command_warnings false\n\n# $fish_lsp_prefer_builtin_fish_commands \n# Show diagnostic `2004` which warns the user when they are using a recognized external command that can be replaced by an equivalent fish builtin command.\n# (Options: 'true', 'false')\n# (Default: 'false')\nset -gx fish_lsp_prefer_builtin_fish_commands false\n\n# $fish_lsp_allow_fish_wrapper_functions \n# Show warnings when `alias`, `export`, etc... are used instead of their equivalent fish builtin commands.\n# Some commands will provide quick-fixes to convert this diagnostic to its equivalent fish command.\n# Diagnostic `2002` is shown when this setting is false, and hidden when true.\n# (Options: 'true', 'false')\n# (Default: 'true')\nset -gx fish_lsp_allow_fish_wrapper_functions true\n\n# $fish_lsp_require_autoloaded_functions_to_have_description \n# Show warning diagnostic `4008` when an autoloaded function definition does not have a description `function -d/--description '...'; end;`\n# (Options: 'true', 'false')\n# (Default: 'true')\nset -gx fish_lsp_require_autoloaded_functions_to_have_description true\n\n# $fish_lsp_max_background_files \n# The maximum number of background files to read into buffer on startup.\n# (Example Options: 100, 250, 500, 1000, 5000, 10000)\n# (Default: 10000)\nset -gx fish_lsp_max_background_files 10000\n\n# $fish_lsp_show_client_popups \n# Should the client receive pop-up window notification requests from the fish-lsp server?\n# (Options: 'true', 'false')\n# (Default: 'false')\nset -gx fish_lsp_show_client_popups true\n\n# $fish_lsp_single_workspace_support \n# Try to limit the fish-lsp's workspace searching to only the current workspace open.\n# (Options: 'true', 'false')\n# (Default: 'false')\nset -gx fish_lsp_single_workspace_support false\n\n# $fish_lsp_ignore_paths \n# Glob paths to never search when indexing their parent folder\n# (Example Options: '**/.git/**', '**/node_modules/**', '**/vendor/**', \n# '**/__pycache__/**', '**/docker/**', \n# '**/containerized/**', '**/*.log', '**/tmp/**')\n# (Default: ['**/.git/**', '**/node_modules/**', '**/containerized/**', \n# '**/docker/**'])\nset -gx fish_lsp_ignore_paths '**/.git/**' '**/node_modules/**' '**/containerized/**' '**/docker/**'\n\n# $fish_lsp_max_workspace_depth \n# The maximum depth for the lsp to search when starting up.\n# (Example Options: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 15, 20)\n# (Default: 5)\nset -gx fish_lsp_max_workspace_depth 3\n\n# $fish_lsp_fish_path \n# A path to the fish executable to use exposing fish binary to use in server's spawned child_processes.\n# Typically, this is used in the language-client's `FishServer.initialize(connection, InitializeParams.initializationOptions)`, NOT as an environment variable\n# (Example Options: 'fish', '/usr/bin/fish', '/usr/.local/bin/fish', \n# '~/.local/bin/fish')\n# (Default: '')\nset -gx fish_lsp_fish_path 'fish'\n```\n\n
\n\n\n\n\n\n\n###### :gear: Complete Configuration Template:
\n\n\n```fish\n# $fish_lsp_enabled_handlersfish-lsp env --create\n\n\n# Enables the fish-lsp handlers. By default, all stable handlers are enabled.\n# (Options: 'complete', 'hover', 'rename', 'definition', 'implementation', \n# 'reference', 'logger', 'formatting', 'formatRange', \n# 'typeFormatting', 'codeAction', 'codeLens', 'folding', \n# 'selectionRange', 'signature', 'executeCommand', 'inlayHint', \n# 'highlight', 'diagnostic', 'popups', 'semanticTokens')\n# (Default: [])\nset -gx fish_lsp_enabled_handlers \n\n# $fish_lsp_disabled_handlers \n# Disables the fish-lsp handlers. By default, non-stable handlers are disabled.\n# (Options: 'complete', 'hover', 'rename', 'definition', 'implementation', \n# 'reference', 'logger', 'formatting', 'formatRange', \n# 'typeFormatting', 'codeAction', 'codeLens', 'folding', \n# 'selectionRange', 'signature', 'executeCommand', 'inlayHint', \n# 'highlight', 'diagnostic', 'popups', 'semanticTokens')\n# (Default: [])\nset -gx fish_lsp_disabled_handlers \n\n# $fish_lsp_commit_characters \n# Array of the completion expansion characters.\n# Single letter values only.\n# Commit characters are used to select completion items, as shortcuts.\n# (Example Options: '.', ',', ';', ':', '(', ')', '[', ']', '{', '}', '<', \n# '>', ''', '\"', '=', '+', '-', '/', '\\', '|', '&', '%', \n# '$', '#', '@', '!', '?', '*', '^', '`', '~', '\\t', ' ')\n# (Default: ['\\t', ';', ' '])\nset -gx fish_lsp_commit_characters \n\n# $fish_lsp_log_file \n# A path to the fish-lsp's logging file. Empty string disables logging.\n# (Example Options: '/tmp/fish_lsp.log', '~/path/to/fish_lsp/logs.txt')\n# (Default: '')\nset -gx fish_lsp_log_file \n\n# $fish_lsp_log_level \n# The logging severity level for displaying messages in the log file.\n# (Options: 'debug', 'info', 'warning', 'error', 'log')\n# (Default: '')\nset -gx fish_lsp_log_level \n\n# $fish_lsp_all_indexed_paths \n# The fish file paths to include in the fish-lsp's startup indexing, as workspaces.\n# Order matters (usually place `$__fish_config_dir` before `$__fish_data_dir`).\n# (Example Options: '$HOME/.config/fish', '/usr/share/fish', \n# '$__fish_config_dir', '$__fish_data_dir')\n# (Default: ['$__fish_config_dir', '$__fish_data_dir'])\nset -gx fish_lsp_all_indexed_paths \n\n# $fish_lsp_modifiable_paths \n# The fish file paths, for workspaces where global symbols can be renamed by the user.\n# (Example Options: '/usr/share/fish', '$HOME/.config/fish', \n# '$__fish_data_dir', '$__fish_config_dir')\n# (Default: ['$__fish_config_dir'])\nset -gx fish_lsp_modifiable_paths \n\n# $fish_lsp_diagnostic_disable_error_codes \n# The diagnostics error codes to disable from the fish-lsp's diagnostics.\n# (Options: 1001, 1002, 1003, 1004, 1005, 2001, 2002, 2003, 2004, 3001, 3002, \n# 3003, 4001, 4002, 4003, 4004, 4005, 4006, 4007, 4008, 5001, 5555, \n# 6001, 7001, 8001, 9999)\n# (Default: [])\nset -gx fish_lsp_diagnostic_disable_error_codes \n\n# $fish_lsp_max_diagnostics \n# The maximum number of diagnostics to return per file.\n# Using value `0` means unlimited diagnostics.\n# To entirely disable diagnostics use `fish_lsp_disabled_handlers`\n# (Example Options: 0, 10, 25, 50, 100, 250)\n# (Default: 0)\nset -gx fish_lsp_max_diagnostics \n\n# $fish_lsp_enable_experimental_diagnostics \n# Enables the experimental diagnostics feature, using `fish --no-execute`.\n# This feature will enable the diagnostic error code 9999 (disabled by default).\n# (Options: 'true', 'false')\n# (Default: 'false')\nset -gx fish_lsp_enable_experimental_diagnostics \n\n# $fish_lsp_strict_conditional_command_warnings \n# Diagnostic `3002` includes/excludes conditionally chained commands to explicitly check existence.\n# ENABLED EXAMPLE: `command -q ls && command ls || echo 'no ls'`\n# DISABLED EXAMPLE: `command ls || echo 'no ls'`\n# (Options: 'true', 'false')\n# (Default: 'false')\nset -gx fish_lsp_strict_conditional_command_warnings \n\n# $fish_lsp_prefer_builtin_fish_commands \n# Show diagnostic `2004` which warns the user when they are using a recognized external command that can be replaced by an equivalent fish builtin command.\n# (Options: 'true', 'false')\n# (Default: 'false')\nset -gx fish_lsp_prefer_builtin_fish_commands \n\n# $fish_lsp_allow_fish_wrapper_functions \n# Show warnings when `alias`, `export`, etc... are used instead of their equivalent fish builtin commands.\n# Some commands will provide quick-fixes to convert this diagnostic to its equivalent fish command.\n# Diagnostic `2002` is shown when this setting is false, and hidden when true.\n# (Options: 'true', 'false')\n# (Default: 'true')\nset -gx fish_lsp_allow_fish_wrapper_functions \n\n# $fish_lsp_require_autoloaded_functions_to_have_description \n# Show warning diagnostic `4008` when an autoloaded function definition does not have a description `function -d/--description '...'; end;`\n# (Options: 'true', 'false')\n# (Default: 'true')\nset -gx fish_lsp_require_autoloaded_functions_to_have_description \n\n# $fish_lsp_max_background_files \n# The maximum number of background files to read into buffer on startup.\n# (Example Options: 100, 250, 500, 1000, 5000, 10000)\n# (Default: 10000)\nset -gx fish_lsp_max_background_files \n\n# $fish_lsp_show_client_popups \n# Should the client receive pop-up window notification requests from the fish-lsp server?\n# (Options: 'true', 'false')\n# (Default: 'false')\nset -gx fish_lsp_show_client_popups \n\n# $fish_lsp_single_workspace_support \n# Try to limit the fish-lsp's workspace searching to only the current workspace open.\n# (Options: 'true', 'false')\n# (Default: 'false')\nset -gx fish_lsp_single_workspace_support \n\n# $fish_lsp_ignore_paths \n# Glob paths to never search when indexing their parent folder\n# (Example Options: '**/.git/**', '**/node_modules/**', '**/vendor/**', \n# '**/__pycache__/**', '**/docker/**', \n# '**/containerized/**', '**/*.log', '**/tmp/**')\n# (Default: ['**/.git/**', '**/node_modules/**', '**/containerized/**', \n# '**/docker/**'])\nset -gx fish_lsp_ignore_paths \n\n# $fish_lsp_max_workspace_depth \n# The maximum depth for the lsp to search when starting up.\n# (Example Options: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 15, 20)\n# (Default: 5)\nset -gx fish_lsp_max_workspace_depth \n\n# $fish_lsp_fish_path \n# A path to the fish executable to use exposing fish binary to use in server's spawned child_processes.\n# Typically, this is used in the language-client's `FishServer.initialize(connection, InitializeParams.initializationOptions)`, NOT as an environment variable\n# (Example Options: 'fish', '/usr/bin/fish', '/usr/.local/bin/fish', \n# '~/.local/bin/fish')\n# (Default: '')\nset -gx fish_lsp_fish_path\n```\n\n
\n\n\n\n\n\n###### :floppy_disk: Formatting as JSON:
\n\n\n```json\n{\n \"fish_lsp_enabled_handlers\": [],\n \"fish_lsp_disabled_handlers\": [],\n \"fish_lsp_commit_characters\": [\n \"\\t\",\n \";\",\n \" \"\n ],\n \"fish_lsp_log_file\": \"\",\n \"fish_lsp_log_level\": \"\",\n \"fish_lsp_all_indexed_paths\": [\n \"$__fish_config_dir\",\n \"$__fish_data_dir\"\n ],\n \"fish_lsp_modifiable_paths\": [\n \"$__fish_config_dir\"\n ],\n \"fish_lsp_diagnostic_disable_error_codes\": [],\n \"fish_lsp_max_diagnostics\": 0,\n \"fish_lsp_enable_experimental_diagnostics\": false,\n \"fish_lsp_strict_conditional_command_warnings\": false,\n \"fish_lsp_prefer_builtin_fish_commands\": false,\n \"fish_lsp_allow_fish_wrapper_functions\": true,\n \"fish_lsp_require_autoloaded_functions_to_have_description\": true,\n \"fish_lsp_max_background_files\": 10000,\n \"fish_lsp_show_client_popups\": true,\n \"fish_lsp_single_workspace_support\": false,\n \"fish_lsp_ignore_paths\": [\n \"**/.git/**\",\n \"**/node_modules/**\",\n \"**/containerized/**\",\n \"**/docker/**\"\n ],\n \"fish_lsp_max_workspace_depth\": 3,\n \"fish_lsp_fish_path\": \"fish\"\n}\n```\n\nfish-lsp env --show-default --json\n\n
\n\n\nFor language clients that import the source code directly and manually connect with the server (e.g., [VSCode](https://github.com/ndonfris/vscode-fish-lsp/blob/4aa63803a0d0a65ceabf164eaeb5a3e360662ef9/package.json#L136)), passing the environment configuration through the [`initializeParams.initializationOptions`](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#initializeParams) is also possible.\n\n#### Command Flags\n\nBoth the flags `--enable` and `--disable` are provided on the `fish-lsp start` subcommand. __Default configuration enables all stable server handlers__.\n\n```fish\n# displays what handlers are enabled. Removing the dump flag will run the server.\nfish-lsp start --disable complete signature --dump \n```\n\n#### Further Server Configuration\n\nAny [flags](#command-flags) will overwrite their corresponding [environment variables](#environment-variables), if both are seen for the `fish-lsp` process. For this reason, it is encouraged to wrap any non-standard behavior of the `fish-lsp` in [functions](https://fishshell.com/docs/current/language.html#functions) or [aliases](https://fishshell.com/docs/current/language.html#defining-aliases).\n\nDue to the vast possibilities this project aims to support in the fish shell, [sharing useful configurations is highly encouraged](https://github.com/ndonfris/fish-lsp/discussions).\n\n##### Project Specific configuration via dot-env\n\nIf you are using the environment variables, or an alias to start the server from a shell instance, you can also use a `.env` file to set project specific overrides.\n\nThis is not directly supported by the server, but can be achieved using the variety of dotenv tools available.[\\[1\\]](https://github.com/berk-karaal/loadenv.fish)[\\[2\\]](https://direnv.net)[\\[3\\]](https://github.com/jdx/mise)[\\[4\\]](https://github.com/hyperupcall/autoenv)\n\n\n\n\n\n\n\n##### Configuration via Disable Comments\n\n\n\n\n\n###### :jigsaw: Writing current values to
\n\n```fish\n## clear the current fish-lsp configuration\n## >_ fish-lsp env --names-only | string split \\n | read -e $name;\n\n## grab only specific variables\nfish-lsp env --show-default --only fish_lsp_all_indexed_paths fish_lsp_diagnostic_disable_error_codes | source\n\n## Write the current fish-lsp configuration to ~/.config/fish/conf.d/fish-lsp.fish\nfish-lsp env --show --confd > ~/.config/fish/conf.d/fish-lsp.fish\n```\n\n~/.config/fish/conf.d/fish-lsp.fish\n\n
![\"nick\"/](\"https://avatars.githubusercontent.com/u/49458459?v=4?s=50\") nick 💻 | \n ![\"mimikun\"/](\"https://avatars.githubusercontent.com/u/13450321?v=4?s=50\") mimikun 💻 | \n ![\"Jaakko](\"https://avatars.githubusercontent.com/u/36770267?v=4?s=50\") Jaakko Paju 💻 | \n ![\"Sean](\"https://avatars.githubusercontent.com/u/1377996?v=4?s=50\") Sean Perry 💻 | \n ![\"Fabio](\"https://avatars.githubusercontent.com/u/385249?v=4?s=50\") Fabio Coatti 💻 | \n ![\"Peter](\"https://avatars.githubusercontent.com/u/16930781?v=4?s=50\") Peter Cardenas 💻 | \n ![\"Peter](\"https://avatars.githubusercontent.com/u/7420227?v=4?s=50\") Peter Tri Ho 💻 | \n
![\"bnwa\"/](\"https://avatars.githubusercontent.com/u/74591246?v=4?s=50\") bnwa 💻 | \n ![\"Branch](\"https://avatars.githubusercontent.com/u/19800529?v=4?s=50\") Branch Vincent 💻 | \n ![\"Jaeseok](\"https://avatars.githubusercontent.com/u/23169202?v=4?s=50\") Jaeseok Lee 💻 | \n ![\"ClanEver\"/](\"https://avatars.githubusercontent.com/u/73160783?v=4?s=50\") ClanEver 💻 | \n ![\"Nathan](\"https://avatars.githubusercontent.com/u/52262673?v=4?s=50\") Nathan DeGruchy 💻 | \n ![\"Nan](\"https://avatars.githubusercontent.com/u/64199650?v=4?s=50\") Nan Huang 💻 | \n ![\"Sola\"/](\"https://avatars.githubusercontent.com/u/3632663?v=4?s=50\") Sola 💻 | \n
![\"Jose](\"https://avatars.githubusercontent.com/u/54108223?v=4?s=50\") Jose Alvarez 💻 | \n ![\"Bernát](\"https://avatars.githubusercontent.com/u/690238?v=4?s=50\") Bernát Gábor 💻 | \n
tag inside - \n // const variableCodeElement = dt.querySelector('code');\n // const nameWithDollar = variableCodeElement?.textContent?.trim() || '';\n //\n // // Clean up the name (remove leading '$')\n // const name = nameWithDollar.startsWith('$') ? nameWithDollar.substring(1) : nameWithDollar;\n //\n // // The description is in the immediately following
- sibling\n // const dd = dt.nextElementSibling;\n // let description = '';\n //\n // if (dd && dd.tagName === 'DD') {\n // // Get the full text content of
- and normalize whitespace\n // description = dd.textContent?.trim().replace(/\\s+/g, ' ') || '';\n // }\n //\n // if (name && description) {\n // specialVariables.push({\n // name: name,\n // description: description,\n // });\n // }\n // });\n\n const sectionLabelSeparator = specialVariables.findIndex(item => item.name === '_');\n if (showArgs['env-variables'].seen && showArgs['special-variables'].seen && keys.length === 2) {\n return specialVariables;\n }\n if (showArgs['env-variables'].seen && keys.length === 1) {\n return specialVariables.slice(sectionLabelSeparator);\n }\n if (showArgs['special-variables'].seen && keys.length === 1) {\n return specialVariables.slice(0, sectionLabelSeparator);\n }\n } catch (error) {\n console.error('Error fetching special variables:', error);\n return [];\n }\n}\n\nfunction stripQuotes(value: string): string {\n const trimmed = value.trim();\n if ((trimmed.startsWith('\"') && trimmed.endsWith('\"')) || (trimmed.startsWith('\\'') && trimmed.endsWith('\\''))) {\n return trimmed.slice(1, -1);\n }\n return trimmed;\n}\n\nfunction tokenizeDefinition(line: string): string[] {\n const tokens: string[] = [];\n let current = '';\n let quote: string | null = null;\n for (let i = 0; i < line.length; i++) {\n const char = line[i]!;\n if (quote) {\n if (char === '\\\\' && quote === '\"' && i + 1 < line.length) {\n current += line[i + 1]!;\n i++;\n continue;\n }\n if (char === quote) {\n tokens.push(current);\n current = '';\n quote = null;\n continue;\n }\n current += char;\n continue;\n }\n if (char === '\"' || char === '\\'') {\n if (current) {\n tokens.push(current);\n current = '';\n }\n quote = char;\n continue;\n }\n if (/\\s/.test(char)) {\n if (current) {\n tokens.push(current);\n current = '';\n }\n continue;\n }\n current += char;\n }\n if (current) tokens.push(current);\n return tokens.filter(Boolean);\n}\n\nfunction parseFunctionLine(line: string): { name: string; flags: string[]; description?: string } | null {\n const match = line.match(/^\\s*function\\s+(.+)$/);\n if (!match) return null;\n const tokens = tokenizeDefinition(match[1]!.trim());\n if (tokens.length === 0) return null;\n const name = tokens.shift()!;\n const flags: string[] = [];\n let description: string | undefined;\n for (let i = 0; i < tokens.length; i++) {\n const token = tokens[i]!;\n if (!token.startsWith('-')) continue;\n let combined = token;\n const next = tokens[i + 1];\n if (next && !next.startsWith('-')) {\n combined = `${token} ${next}`;\n i++;\n if ((token === '--description' || token === '-d') && next) {\n description = stripQuotes(next);\n }\n }\n flags.push(combined.trim());\n }\n return { name, flags, description };\n}\n\nfunction resolveFishDataDir(): string | null {\n const candidateEnv = process.env.__fish_data_dir;\n const candidates = [\n candidateEnv,\n (() => {\n try {\n const result = execSync('fish -c \"printf %s $__fish_data_dir\"', { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });\n return result.trim() || null;\n } catch {\n return null;\n }\n })(),\n '/usr/share/fish',\n '/usr/local/share/fish',\n ].filter((value): value is string => Boolean(value));\n\n for (const candidate of candidates) {\n const functionsDir = path.join(candidate, 'functions');\n if (fsSync.existsSync(functionsDir)) {\n return candidate;\n }\n }\n return null;\n}\n\nasync function fetchFishFunctions(): Promise
{\n const dataDir = resolveFishDataDir();\n if (!dataDir) {\n console.error('Unable to locate $__fish_data_dir. Is fish installed?');\n return [];\n }\n const functionsDir = path.join(dataDir, 'functions');\n const entries = await fs.readdir(functionsDir, { withFileTypes: true });\n const results = new Map();\n for (const entry of entries) {\n if (!entry.isFile() || !entry.name.endsWith('.fish')) continue;\n const filePath = path.join(functionsDir, entry.name);\n const fileContents = await fs.readFile(filePath, 'utf8');\n const definitionLine = fileContents.split(/\\r?\\n/).find(line => line.trim().startsWith('function '));\n if (!definitionLine) continue;\n const parsed = parseFunctionLine(definitionLine);\n if (!parsed) continue;\n const relativeFunctionsPath = path.relative(path.join(dataDir, 'functions'), filePath).replace(/\\\\/g, '/');\n const fileReference = relativeFunctionsPath\n ? `$__fish_data_dir/functions/${relativeFunctionsPath}`\n : '$__fish_data_dir/functions';\n results.set(parsed.name, {\n name: parsed.name,\n file: fileReference,\n flags: parsed.flags,\n description: parsed.description,\n });\n }\n return [...results.values()].sort((a, b) => a.name.localeCompare(b.name));\n}\n\nasync function fetchDataset(target: DatasetType): Promise {\n switch (target) {\n case 'commands':\n return fetchFishCommands();\n case 'functions':\n return fetchFishFunctions();\n case 'special-variables':\n return fetchSpecialVariables('special-variables');\n case 'env-variables':\n return fetchSpecialVariables('env-variables');\n default:\n return [];\n }\n}\n\nasync function main() {\n try {\n const snippetsDir = path.join(process.cwd(), 'src', 'snippets');\n const requestedTargets: DatasetType[] = hasShowArg ? [...showArgsArray] as DatasetType[] : ['commands'];\n if (requestedTargets.length === 0) {\n requestedTargets.push('commands');\n }\n const uniqueTargets = [...new Set(requestedTargets)];\n\n if (uniqueTargets.length === 0) {\n console.error('No action specified. Use --help for usage.');\n return;\n }\n\n for (const target of uniqueTargets) {\n const dataset = await fetchDataset(target);\n if (!dataset || dataset.length === 0) {\n console.error(`No data found for \"${target}\".`);\n continue;\n }\n const jsonOutput = JSON.stringify(dataset, null, 2);\n\n // Handle --diff flag\n if (diffOutput) {\n const outputPath = path.join(snippetsDir, datasetConfig[target].outputFile);\n try {\n const existingContent = await fs.readFile(outputPath, 'utf8');\n const existingJson = JSON.parse(existingContent);\n const existingFormatted = JSON.stringify(existingJson, null, 2);\n\n if (existingFormatted === jsonOutput) {\n console.error(`No changes for ${target}`);\n } else {\n console.error(`\\n=== Diff for ${target} (${outputPath}) ===`);\n const existingLines = existingFormatted.split('\\n');\n const newLines = jsonOutput.split('\\n');\n const maxLines = Math.max(existingLines.length, newLines.length);\n\n for (let i = 0; i < maxLines; i++) {\n const oldLine = existingLines[i] || '';\n const newLine = newLines[i] || '';\n if (oldLine !== newLine) {\n if (oldLine) console.error(`- ${oldLine}`);\n if (newLine) console.error(`+ ${newLine}`);\n }\n }\n }\n } catch (error) {\n console.error(`No existing file for ${target} at ${outputPath}`);\n console.error(`New content would be:\\n${jsonOutput}`);\n }\n continue;\n }\n\n if (!writeOutput) {\n process.stdout.write(jsonOutput + '\\n');\n continue;\n }\n\n try {\n await fs.access(snippetsDir);\n } catch (error) {\n console.error(`Error: Directory '${snippetsDir}' does not exist.`);\n console.error('Please create the directory first before using --write option.');\n process.exit(1);\n }\n\n const outputPath = path.join(snippetsDir, datasetConfig[target].outputFile);\n await fs.writeFile(outputPath, jsonOutput);\n console.error(`${target} data written to ${outputPath}`);\n }\n\n } catch (error) {\n console.error('General Error:', error);\n process.exit(1);\n }\n}\n\nmain();\n"
},
{
"path": "scripts/publish-nightly.fish",
"content": "#!/usr/bin/env fish\n\n# ┌──────────────────────────────┐\n# │ Imported variables/functions │\n# └──────────────────────────────┘\nsource ./scripts/fish/continue-or-exit.fish\nsource ./scripts/fish/pretty-print.fish\nsource ./scripts/fish/utils.fish\n\n# ┌─────────────────┐\n# │ Parse arguments │\n# └─────────────────┘\nargparse \\\n -x c,d -x c,bump-pre -x c,skip-confirm -x i,skip-confirm \\\n h/help c/complete d/dry-run bump-pre skip-confirm i/interactive -- $argv\nor exit 1\n\n# ┌──────────────────────┐\n# │ Execution mode setup │\n# └──────────────────────┘\nset -g DRY_RUN (set -q _flag_dry_run && echo 'true' || echo 'false')\nset -g SKIP_CONFIRM (set -q _flag_skip_confirm && echo 'true' || echo 'false')\nset -g INTERACTIVE (set -q _flag_interactive && echo 'true' || echo 'false')\n\n# ┌────────────────────────────────────┐\n# │ handle flags that cause early exit │\n# └────────────────────────────────────┘\n\n# Help flags: `-h` or `--help`\nif set -q _flag_help\n echo -e \"Usage: publish-nightly.fish [--dry-run] [--skip-confirm] [-c | --complete] [-h | --help] [--bump-pre]\\n\"\n echo -e \"Publishes current `package.json` version to npm with nightly tags\"\n echo -e \"\\nOptions:\\n\"\n echo -e \" -h, --help Show this help message and exit\"\n echo -e \" -d, --dry-run Show what would be done without making changes\"\n echo -e \" --skip-confirm Skip all confirmation prompts\"\n echo -e \" -c, --complete Show completion commands for this script\"\n echo -e \" --bump-pre Bump the preminor version and exit\"\n echo -e \" -i, --interactive Prompt for confirmation before each step (overrides --skip-confirm)\\n\"\n echo -e \"\\nExamples:\\n\"\n echo -e \" >_ ./scripts/publish-nightly.fish --dry-run\"\n echo -e \" Output the steps that would be taken without executing them\\n\"\n echo -e \" >_ ./scripts/publish-nightly.fish --bump-pre && ./scripts/publish-nightly.fish\"\n echo -e \" Bump the preminor version and then publish it\\n\"\n echo -e \" >_ ./scripts/publish-nightly.fish --skip-confirm\"\n echo -e \" Skip all confirmation prompts and publish the next release\\n\"\n exit 0\nend\n\n# Bump preminor flag: `--bump-pre`\nif set -q _flag_bump_pre\n # Get the current preminor version from npm, increment it, and format the new version string\n set latest_version (npm show \"fish-lsp@preminor\" version 2>/dev/null)\n set next_version (get_next_npm_preminor_version)\n # Execute the version bump command\n exec_cmd \"Bump preminor version `$latest_version` → `$next_version`\" \"npm pkg set version=$next_version\" --interactive\n and log_info '✅' '[SUCCESS]' \"Bumped preminor version to `$next_version`\"\n or fail \"Failed to bump preminor version\"\nend\n\n# Completion flag: `-c` or `--complete`\nif set -q _flag_complete\n set -l script (path resolve -- (status current-filename))\n echo \"# COMPLETIONS FROM `$script -c`\n complete --path $script -f\n complete --path $script -s h -l help -d 'Show this help message'\n complete --path $script -s d -l dry-run -d 'Show what would happen without executing'\n complete --path $script -s c -l complete -d 'Show completion commands for this script'\n complete --path $script -l skip-confirm -d 'Don\\'t prompt for confirmation'\n complete --path $script -l bump-pre -d 'Bump the preminor version and exit'\n complete --path $script -s i -l interactive -d 'Prompt for confirmation before each step (overrides --skip-confirm)'\n # yarn publish-nightly\n complete -c yarn -n '__fish_seen_subcommand_from publish-nightly' -f\n complete -c yarn -n '__fish_seen_subcommand_from publish-nightly' -s h -l help -d 'Show this help message'\n complete -c yarn -n '__fish_seen_subcommand_from publish-nightly' -s d -l dry-run -d 'Show what would happen without executing'\n complete -c yarn -n '__fish_seen_subcommand_from publish-nightly' -s c -l complete -d 'Show completion commands for this script'\n complete -c yarn -n '__fish_seen_subcommand_from publish-nightly' -l skip-confirm -d 'Don\\'t prompt for confirmation'\n complete -c yarn -n '__fish_seen_subcommand_from publish-nightly' -l bump-pre -d 'Bump the preminor version and exit'\n complete -c yarn -n '__fish_seen_subcommand_from publish-nightly' -s i -l interactive -d 'Prompt for confirmation before each step (overrides --skip-confirm)'\n \" | string trim -l\n exit 0\nend\n\n# ┌────────────────┐\n# │ main execution │\n# └────────────────┘\nlog_info '' '[INFO]' \"Starting$BOLD_BLUE nightly+preminor$CYAN publish...\"\n\n# ┌──────────────────────┐\n# │ setup info variables │\n# └──────────────────────┘\nset package_name (get_npm_pkg_name)\nset package_version (get_npm_pkg_version)\ntest -z \"$package_name\" -o -z \"$package_version\"; and fail \"Cannot read package.json\"\nlog_info '📦' '[INFO]' \"Package: $BLUE$package_name@$package_version$NORMAL\"\nset git_tag \"v$package_version\"\nset npm_url (get_npm_url)\n\n# ┌─────────────────────┐\n# │ check tag conflicts │\n# └─────────────────────┘\ncheck_and_fix_tag; or fail \"Pre-publish checks failed\"\n\n# ┌───────────────┐\n# │ Confirm BEGIN │\n# └───────────────┘\nlog_info '📋' '[PLAN]' \"Package: $BLUE$package_name@$package_version$NORMAL →$GREEN npm:preminor,nightly$NORMAL +$BRIGHT_GREEN git:$git_tag$NORMAL\"\nconfirm \"Proceed with publish\"; or fail \"Aborted by user\"\n\n# ┌───────────────────────┐\n# │ Execute publish steps │\n# └───────────────────────┘\n# npm\nexec_cmd \"Publish to npm\" \"npm publish --tag preminor\" --interactive --numbered; or fail \"npm publish failed\"\nexec_cmd \"Add nightly tag\" \"npm dist-tag add $package_name@$package_version nightly\" --interactive --numbered; or fail \"dist-tag failed\"\n# git \nexec_cmd \"Create git tag\" \"git tag -a $git_tag -m 'Published to npm: $npm_url'\" --interactive --numbered; or fail \"git tag failed\"\nexec_cmd \"Push git tag\" \"git push origin $git_tag\" --interactive --numbered; or fail \"git push failed\"\n\n# ┌───────────────────────┐\n# │ Final success message │\n# └───────────────────────┘\nnot $DRY_RUN; and log_info '✅' '[SUCCESS]' \"Published $BLUE$package_name@$package_version$NORMAL\"\n$DRY_RUN; and log_info '' '[DRY RUN]' \"Would have published: $BLUE$package_name@$package_version$NORMAL\"\nor log_info '' '[DONE]' 'Finished successfully'\n"
},
{
"path": "scripts/relink-locally.fish",
"content": "#!/usr/bin/env fish\n\n\n# Relink a globally installed package to the local package\n# that was called by this script. If the global package\n# is not installed, it will be installed globally.\n# Use this for testing changes to the fish-lsp package.\n\n# Usage: ./relink-locally.sh\nsource ./scripts/fish/pretty-print.fish\n\nargparse --max-args 1 h/help q/quiet v/verbose no-stderr -- $argv\nor return\n\nif set -q _flag_help\n echo 'NAME:'\n echo ' relink-locally.fish'\n echo ''\n echo 'DESCRIPTION:'\n echo ' Handle relinking pkg. Default usage silences any subshell relinking output.'\n echo ' Option \\'-q,--quiet\\' (silence all subsubshell output), is assumed for'\n echo ' usage without an option.'\n echo ''\n echo 'OPTIONS:'\n echo -e ' -q,--quiet\\tsilence all [DEFAULT]'\n echo -e ' -v,--verbose\\tno silencing subshells'\n echo -e ' --no-stderr\\tsilence stderr in subshells'\n echo -e ' -h,--help\\tshow this message'\n return 0\nend\n\nif set -q _flag_no_stderr\n # show all sub shells w/ only stdout\n if command -vq fish-lsp\n echo ' \"fish-lsp\" is already installed'\n echo ' UNLINKING and LINKING again'\n yarn unlink --global fish-lsp 2>/dev/null\n yarn global remove fish-lsp 2>/dev/null\n end\n yarn link --global fish-lsp --force 2>/dev/null\n echo 'SUCCESS! \"fish-lsp\" is now installed and linked'\n return 0\n\nelse if set -q _flag_verbose\n\n # show all sub shells w/ stdout stderr\n if command -vq fish-lsp\n echo ' \"fish-lsp\" is already installed'\n echo ' UNLINKING and LINKING again'\n yarn unlink --global fish-lsp\n or return 1\n yarn global remove fish-lsp\n or return 1\n end\n yarn link --global fish-lsp --force\n and echo 'SUCCESS! \"fish-lsp\" is now installed and linked'\n\n\n return $status\n\nelse\n # silence all sub shells (don't include stdout & stderr) \n # occurs when: ZERO flags given or $_flag_quiet\n echo $YELLOW\" RELINKING $BLUE\\\"fish-lsp\\\"$YELLOW GLOBALLY...\"$NORMAL\n if command -vq fish-lsp\n echo $YELLOW\" $(icon_warning) command $BLUE\\\"fish-lsp\\\"$YELLOW is already installed\"$NORMAL\n echo $YELLOW\" $(icon_file) UNLINKING and LINKING again\"$NORMAL\n yarn unlink --global fish-lsp &>/dev/null\n yarn global remove fish-lsp &>/dev/null\n end\n yarn link --global fish-lsp --force &>/dev/null\n\n # echo -e $BOLD_GREEN\"$(icon_check)SUCCESS! $BLUE\\\"fish-lsp\\\"$BOLD_GREEN is now installed and linked\"$NORMAL\n print_success \"$BLUE\\\"fish-lsp\\\"$GREEN is now installed and linked globally\"\n return 0\n\nend\n"
},
{
"path": "scripts/update-changelog.fish",
"content": "#!/usr/bin/env fish\n\nsource ./scripts/fish/pretty-print.fish\nsource ./scripts/fish/continue-or-exit.fish\n\nlog_info ' ' '[RUN]' 'Update `docs/CHANGELOG.md` SCRIPT'\nprint_separator\nlog_info 'ℹ️' '[INFO]' 'Dry run of how the `docs/CHANGELOG.md` will be updated...'\nprint_separator\nyarn -s util:update-changelog:dry:diff 2>/dev/null\nprint_separator\n\n# continue_or_exit --quiet --prepend-prompt='This will update the `./docs/CHANGELOG.md`. Do you want to continue?' --prompt-str='(y/n)?'\nif not continue_or_exit --time-in-prompt --quiet --prepend-prompt='This will update the `./docs/CHANGELOG.md`. Do you want to continue?' --prompt-str=\"$GREEN$BOLD$UNDERLINE$REVERSE(y/n)?$NORMAL\"' ' || false\n log_warning '⚠️' '[WARNING]' 'SKIPPING `docs/CHANGELOG.md` UPDATE'\nelse\n yarn util:update-changelog\n log_info '✅' '[INFO]' 'UPDATED `docs/CHANGELOG.md`'\nend\nprint_separator\n"
},
{
"path": "scripts/update-codeblocks-in-docs.ts",
"content": "#!/usr/bin/env tsx\n\n/**\n * Script to update markdown code blocks based on special HTML comments\n *\n * This script searches for HTML comments in the format:\n * \n * ```language\n * old content\n * ```\n *\n * For each comment found, it:\n * 1. Extracts the command after the colon\n * 2. Executes the command in fish shell\n * 3. Replaces only the code block content (preserving the ```language markers)\n *\n * Usage:\n * tsx scripts/update-codeblocks-in-docs.ts [--dry-run] [path]\n *\n * Options:\n * --dry-run Show what would be changed without modifying files\n * path Absolute path to a file or directory to process (optional)\n * If not provided, searches all markdown files in the workspace\n */\n\nimport { execSync } from 'child_process';\nimport { readFileSync, writeFileSync, existsSync, statSync } from 'fs';\nimport { join, dirname, resolve } from 'path';\nimport { fileURLToPath } from 'url';\nimport fg from 'fast-glob';\n\nconst __filename = fileURLToPath(import.meta.url);\nconst __dirname = dirname(__filename);\n\nconst WORKSPACE_ROOT = resolve(__dirname, '..');\nconst DRY_RUN = process.argv.includes('--dry-run');\n\n// Get custom path from args (filter out script name, node, tsx, and flags)\nconst args = process.argv.slice(2).filter(arg => !arg.includes('--') && !arg.includes('node_modules') && !arg.endsWith('.ts'));\nconst customPath = args.length > 0 ? resolve(args[0]) : undefined;\n\ninterface UpdateDirective {\n lineNumber: number;\n command: string;\n}\n\nfunction extractUpdateDirectives(content: string): UpdateDirective[] {\n const lines = content.split('\\n');\n const directives: UpdateDirective[] = [];\n const pattern = //;\n\n lines.forEach((line, index) => {\n const match = line.match(pattern);\n if (match && match[1]) {\n directives.push({\n lineNumber: index,\n command: match[1].trim(),\n });\n }\n });\n\n return directives;\n}\n\nfunction executeCommand(command: string): { output: string; status: number } {\n try {\n const output = execSync(command, {\n encoding: 'utf-8',\n shell: '/usr/bin/fish',\n stdio: ['pipe', 'pipe', 'pipe'],\n });\n return { output: output.trimEnd(), status: 0 };\n } catch (error: any) {\n return {\n output: error.stdout?.toString() || error.stderr?.toString() || '',\n status: error.status || 1,\n };\n }\n}\n\nfunction processReadme(content: string, filePath: string): { newContent: string; updatesCount: number } {\n const lines = content.split('\\n');\n const directives = extractUpdateDirectives(content);\n \n if (directives.length === 0) {\n return { newContent: content, updatesCount: 0 };\n }\n\n let updatesCount = 0;\n const output: string[] = [];\n let i = 0;\n\n while (i < lines.length) {\n const line = lines[i];\n\n // Check if current line has an update directive\n const directive = directives.find(d => d.lineNumber === i);\n\n if (directive) {\n console.error(` ✓ Line ${i + 1}: ${directive.command}`);\n\n // Add the comment line\n output.push(line);\n i++;\n\n // Find the opening backticks\n while (i < lines.length) {\n const currentLine = lines[i];\n \n if (currentLine.match(/^```/)) {\n // Found opening backticks - preserve them\n const codeblockOpening = currentLine;\n output.push(codeblockOpening);\n i++;\n\n // Execute command\n console.error(` Executing: ${directive.command}`);\n const { output: commandOutput, status } = executeCommand(directive.command);\n \n if (status !== 0) {\n console.error(` ❌ Error: Command exited with status ${status} - skipping update`);\n \n // Command failed - keep old content\n while (i < lines.length) {\n const contentLine = lines[i];\n output.push(contentLine);\n \n if (contentLine.match(/^```/)) {\n // Found closing backticks\n i++;\n break;\n }\n \n i++;\n }\n break;\n }\n\n // Add new content (command succeeded)\n output.push(commandOutput);\n\n // Skip old content until closing backticks\n while (i < lines.length) {\n const contentLine = lines[i];\n \n if (contentLine.match(/^```/)) {\n // Found closing backticks\n output.push(contentLine);\n i++;\n break;\n }\n \n // Skip old content line\n i++;\n }\n\n updatesCount++;\n break;\n }\n \n // Line between comment and codeblock\n output.push(currentLine);\n i++;\n }\n } else {\n // Regular line\n output.push(line);\n i++;\n }\n }\n\n return { newContent: output.join('\\n'), updatesCount };\n}\n\nfunction getMarkdownFiles(targetPath?: string): string[] {\n if (targetPath) {\n // Check if path exists\n if (!existsSync(targetPath)) {\n console.error(`Error: Path does not exist: ${targetPath}`);\n process.exit(1);\n }\n\n const stats = statSync(targetPath);\n \n if (stats.isFile()) {\n // Single file - verify it's a markdown file\n if (!targetPath.endsWith('.md')) {\n console.error(`Error: File is not a markdown file: ${targetPath}`);\n process.exit(1);\n }\n return [targetPath];\n } else if (stats.isDirectory()) {\n // Directory - find all markdown files\n return fg.sync('**/*.md', {\n cwd: targetPath,\n absolute: true,\n ignore: ['**/node_modules/**', '**/.git/**'],\n });\n }\n }\n\n // No path provided - search workspace\n return fg.sync('**/*.md', {\n cwd: WORKSPACE_ROOT,\n absolute: true,\n ignore: ['**/node_modules/**', '**/.git/**'],\n });\n}\n\nfunction processFile(filePath: string): { updated: boolean; updatesCount: number } {\n const content = readFileSync(filePath, 'utf-8');\n const directives = extractUpdateDirectives(content);\n\n if (directives.length === 0) {\n return { updated: false, updatesCount: 0 };\n }\n\n console.log(`\\n📄 Processing: ${filePath}`);\n console.log(` Found ${directives.length} directive(s)\\n`);\n\n const { newContent, updatesCount } = processReadme(content, filePath);\n\n if (!DRY_RUN && updatesCount > 0) {\n writeFileSync(filePath, newContent, 'utf-8');\n }\n\n return { updated: updatesCount > 0, updatesCount };\n}\n\nfunction main() {\n if (DRY_RUN) {\n console.log('🔍 DRY RUN MODE - No files will be modified\\n');\n }\n\n console.log('Scanning for markdown files with FISH_LSP_UPDATE_CODEBLOCK directives...\\n');\n\n // Get markdown files to process\n const markdownFiles = getMarkdownFiles(customPath);\n\n if (markdownFiles.length === 0) {\n console.log('No markdown files found.');\n process.exit(0);\n }\n\n console.log(`Found ${markdownFiles.length} markdown file(s) to scan\\n`);\n\n // Process each file\n let totalDirectives = 0;\n let totalUpdates = 0;\n let filesUpdated = 0;\n\n for (const filePath of markdownFiles) {\n const { updated, updatesCount } = processFile(filePath);\n \n if (updated) {\n filesUpdated++;\n totalUpdates += updatesCount;\n }\n\n // Count directives in file\n const content = readFileSync(filePath, 'utf-8');\n const directives = extractUpdateDirectives(content);\n totalDirectives += directives.length;\n }\n\n // Summary\n console.log('\\n' + '='.repeat(60));\n if (DRY_RUN) {\n console.log('🔍 DRY RUN COMPLETE - No changes were made');\n console.log(` Scanned ${markdownFiles.length} file(s)`);\n console.log(` Found ${totalDirectives} directive(s) in ${filesUpdated} file(s)`);\n console.log(` Would update ${totalUpdates} codeblock(s)`);\n } else {\n console.log('✨ Processing complete!');\n console.log(` Scanned ${markdownFiles.length} file(s)`);\n console.log(` Found ${totalDirectives} directive(s) in ${filesUpdated} file(s)`);\n console.log(` Updated ${totalUpdates} codeblock(s)`);\n }\n}\n\nmain();\n"
},
{
"path": "scripts/workspace-cli.ts",
"content": "#!/usr/bin/env tsx\n\nimport { Command } from 'commander';\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport * as child_process from 'child_process';\nimport fastGlob from 'fast-glob';\nimport chalk from 'chalk';\n\n// Minimal types for CLI usage (no LSP dependencies)\ninterface TestFileSpec {\n relativePath: string;\n content: string | string[];\n}\n\ninterface WorkspaceSnapshot {\n name: string;\n files: TestFileSpec[];\n timestamp: number;\n}\n\nclass WorkspaceCLI {\n static fromSnapshot(snapshotPath: string): { name: string; files: TestFileSpec[] } {\n if (!fs.existsSync(snapshotPath)) {\n throw new Error(`Snapshot file not found: ${snapshotPath}`);\n }\n\n const snapshotContent = fs.readFileSync(snapshotPath, 'utf8');\n const snapshot: WorkspaceSnapshot = JSON.parse(snapshotContent);\n \n return { name: snapshot.name, files: snapshot.files };\n }\n\n static convertSnapshotToWorkspace(snapshotPath: string, outputDir?: string): string {\n const snapshot = this.fromSnapshot(snapshotPath);\n const workspacePath = outputDir || path.join('tests/workspaces', snapshot.name);\n \n // Create workspace directory\n fs.mkdirSync(workspacePath, { recursive: true });\n \n // Create fish directory structure\n const fishDirs = new Set();\n snapshot.files.forEach(file => {\n const dir = path.dirname(file.relativePath);\n if (dir !== '.') fishDirs.add(dir);\n });\n \n fishDirs.forEach(dir => {\n const dirPath = path.join(workspacePath, dir);\n fs.mkdirSync(dirPath, { recursive: true });\n });\n \n // Write files\n snapshot.files.forEach(file => {\n const filePath = path.join(workspacePath, file.relativePath);\n const content = Array.isArray(file.content) ? file.content.join('\\n') : file.content;\n fs.writeFileSync(filePath, content, 'utf8');\n });\n \n return workspacePath;\n }\n\n static readWorkspace(folderPath: string): { path: string; files: string[] } {\n const absPath = path.isAbsolute(folderPath) \n ? folderPath \n : fs.existsSync(path.join('tests/workspaces', folderPath))\n ? path.resolve(path.join('tests/workspaces', folderPath))\n : path.resolve(folderPath);\n\n if (!fs.existsSync(absPath)) {\n throw new Error(`Workspace directory not found: ${absPath}`);\n }\n\n // Check if there's a fish subdirectory\n let searchPath = absPath;\n if (fs.existsSync(path.join(absPath, 'fish')) && fs.statSync(path.join(absPath, 'fish')).isDirectory()) {\n searchPath = path.join(absPath, 'fish');\n }\n\n const files = fastGlob.sync(['**/*.fish'], { cwd: searchPath });\n return { path: absPath, files };\n }\n\n static convertWorkspaceToSnapshot(folderPath: string, outputPath?: string): string {\n const workspace = this.readWorkspace(folderPath);\n \n // Check if there's a fish subdirectory\n let searchPath = workspace.path;\n if (fs.existsSync(path.join(workspace.path, 'fish'))) {\n searchPath = path.join(workspace.path, 'fish');\n }\n \n const files: TestFileSpec[] = [];\n workspace.files.forEach(relPath => {\n const fullPath = path.join(searchPath, relPath);\n const content = fs.readFileSync(fullPath, 'utf8');\n files.push({ relativePath: relPath, content });\n });\n \n const snapshot: WorkspaceSnapshot = {\n name: path.basename(workspace.path),\n files,\n timestamp: Date.now()\n };\n \n const snapshotPath = outputPath || path.join(path.dirname(workspace.path), `${snapshot.name}.snapshot`);\n fs.writeFileSync(snapshotPath, JSON.stringify(snapshot, null, 2));\n \n return snapshotPath;\n }\n\n static showFileTree(dirPath: string): string {\n if (!fs.existsSync(dirPath)) {\n return 'Directory not found';\n }\n\n const tree: string[] = [];\n const buildTree = (dir: string, prefix = '') => {\n const entries = fs.readdirSync(dir, { withFileTypes: true });\n entries.forEach((entry, index) => {\n const isLast = index === entries.length - 1;\n const currentPrefix = prefix + (isLast ? '└── ' : '├── ');\n tree.push(currentPrefix + entry.name);\n\n if (entry.isDirectory()) {\n const nextPrefix = prefix + (isLast ? ' ' : '│ ');\n buildTree(path.join(dir, entry.name), nextPrefix);\n }\n });\n };\n\n tree.push(path.basename(dirPath) + '/');\n buildTree(dirPath, '');\n return tree.join('\\n');\n }\n\n static async showTreeSitterAST(folderPath: string, useColors: boolean = true): Promise {\n const workspace = this.readWorkspace(folderPath);\n let searchPath = workspace.path;\n if (fs.existsSync(path.join(workspace.path, 'fish'))) {\n searchPath = path.join(workspace.path, 'fish');\n }\n\n for (let idx = 0; idx < workspace.files.length; idx++) {\n const relPath = workspace.files[idx];\n const fullPath = path.join(searchPath, relPath);\n \n try {\n // Use child_process to call fish-lsp info --dump-parse-tree\n const colorFlag = useColors ? '' : '--no-color';\n const cmd = `fish-lsp info --dump-parse-tree ${colorFlag} \"${fullPath}\"`;\n \n const result = child_process.execSync(cmd, { \n encoding: 'utf8',\n stdio: ['pipe', 'pipe', 'pipe']\n });\n \n if (idx > 0) console.log(chalk.white('---------------------------------------------'));\n console.log('file:', chalk.green(`${relPath}`));\n console.log();\n console.log(result);\n if (idx < workspace.files.length - 1) {\n console.log();\n }\n } catch (error) {\n console.error(`❌ Error parsing ${relPath}:`, error.message);\n if (error.stderr) {\n console.error(`stderr: ${error.stderr}`);\n }\n }\n }\n }\n\n}\n\n// Generate fish shell completions for yarn sh:workspace-cli\nfunction generateFishCompletions(): void {\n console.log(`complete -c yarn -n \"__fish_seen_subcommand_from sh:workspace-cli\" -f`);\n console.log(`complete -c yarn -n \"__fish_seen_subcommand_from sh:workspace-cli\" -s h -l help -d \"Show help\"`);\n console.log(`complete -c yarn -n \"__fish_seen_subcommand_from sh:workspace-cli\" -s V -l version -d \"Show version\"`);\n console.log(`complete -c yarn -n \"__fish_seen_subcommand_from sh:workspace-cli\" -s c -l completions -d \"Generate fish completions\"`);\n\n // read command\n console.log(`complete -c yarn -n \"__fish_seen_subcommand_from sh:workspace-cli\" -n \"not __fish_seen_subcommand_from read snapshot-to-workspace workspace-to-snapshot show help\" -a \"read\" -d \"Read and display workspace from directory\"`);\n console.log(`complete -c yarn -n \"__fish_seen_subcommand_from sh:workspace-cli\" -n \"__fish_seen_subcommand_from read\" -l show-tree -d \"Show file tree\"`);\n console.log(`complete -c yarn -n \"__fish_seen_subcommand_from sh:workspace-cli\" -n \"__fish_seen_subcommand_from read\" -F`);\n\n // snapshot-to-workspace command\n console.log(`complete -c yarn -n \"__fish_seen_subcommand_from sh:workspace-cli\" -n \"not __fish_seen_subcommand_from read snapshot-to-workspace workspace-to-snapshot show help\" -a \"snapshot-to-workspace\" -d \"Convert snapshot file to workspace directory\"`);\n console.log(`complete -c yarn -n \"__fish_seen_subcommand_from sh:workspace-cli\" -n \"__fish_seen_subcommand_from snapshot-to-workspace\" -s o -l output -d \"Output directory\" -F`);\n console.log(`complete -c yarn -n \"__fish_seen_subcommand_from sh:workspace-cli\" -n \"__fish_seen_subcommand_from snapshot-to-workspace\" -k -xa \"(find . -name '*.snapshot' -type f 2>/dev/null)\"`);\n\n // workspace-to-snapshot command\n console.log(`complete -c yarn -n \"__fish_seen_subcommand_from sh:workspace-cli\" -n \"not __fish_seen_subcommand_from read snapshot-to-workspace workspace-to-snapshot show help\" -a \"workspace-to-snapshot\" -d \"Convert workspace directory to snapshot file\"`);\n console.log(`complete -c yarn -n \"__fish_seen_subcommand_from sh:workspace-cli\" -n \"__fish_seen_subcommand_from workspace-to-snapshot\" -s o -l output -d \"Output snapshot file path\" -F`);\n console.log(`complete -c yarn -n \"__fish_seen_subcommand_from sh:workspace-cli\" -n \"__fish_seen_subcommand_from workspace-to-snapshot\" -F`);\n\n // show command\n console.log(`complete -c yarn -n \"__fish_seen_subcommand_from sh:workspace-cli\" -n \"not __fish_seen_subcommand_from read snapshot-to-workspace workspace-to-snapshot show help\" -a \"show\" -d \"Display snapshot or workspace contents\"`);\n console.log(`complete -c yarn -n \"__fish_seen_subcommand_from sh:workspace-cli\" -n \"__fish_seen_subcommand_from show\" -l show-tree -d \"Show file tree (for workspaces)\"`);\n console.log(`complete -c yarn -n \"__fish_seen_subcommand_from sh:workspace-cli\" -n \"__fish_seen_subcommand_from show\" -l show-tree-sitter-ast -d \"Show Tree-sitter AST for each fish file (for workspaces)\"`);\n console.log(`complete -c yarn -n \"__fish_seen_subcommand_from sh:workspace-cli\" -n \"__fish_seen_subcommand_from show\" -l no-color -d \"Disable color output for Tree-sitter AST\"`);\n console.log(`complete -c yarn -n \"__fish_seen_subcommand_from sh:workspace-cli\" -n \"__fish_seen_subcommand_from show\" -F`);\n console.log(`complete -c yarn -n \"__fish_seen_subcommand_from sh:workspace-cli\" -n \"__fish_seen_subcommand_from show\" -k -xa \"(find . -name '*.snapshot' -type f 2>/dev/null)\"`);\n\n // help command\n console.log(`complete -c yarn -n \"__fish_seen_subcommand_from sh:workspace-cli\" -n \"not __fish_seen_subcommand_from read snapshot-to-workspace workspace-to-snapshot show help\" -a \"help\" -d \"Display help for command\"`);\n console.log(`complete -c yarn -n \"__fish_seen_subcommand_from sh:workspace-cli\" -n \"__fish_seen_subcommand_from help\" -xa \"read snapshot-to-workspace workspace-to-snapshot show\"`);\n}\n\n// CLI setup\nconst program = new Command()\n .name('workspace-cli')\n .description('Test workspace utilities - convert between snapshots and folders')\n .version('1.0.0')\n .option('-c, --completions', 'Generate fish shell completions');\n\nprogram\n .command('read')\n .description('Read and display workspace from directory')\n .argument('', 'Path to workspace directory')\n .option('--show-tree', 'Show file tree')\n .action((workspacePath, options) => {\n try {\n const workspace = WorkspaceCLI.readWorkspace(workspacePath);\n console.log(`📁 Workspace: ${workspace.path}`);\n console.log(`📄 Found ${workspace.files.length} fish files`);\n \n workspace.files.forEach(file => {\n console.log(` ${file}`);\n });\n \n if (options.showTree) {\n console.log('\\n🌳 File tree:');\n console.log(WorkspaceCLI.showFileTree(workspace.path));\n }\n } catch (error) {\n console.error('❌ Error:', error.message);\n process.exit(1);\n }\n });\n\nprogram\n .command('snapshot-to-workspace')\n .description('Convert snapshot file to workspace directory')\n .argument('', 'Path to snapshot file')\n .option('-o, --output ', 'Output directory')\n .action((snapshotPath, options) => {\n try {\n const workspacePath = WorkspaceCLI.convertSnapshotToWorkspace(snapshotPath, options.output);\n console.log(`✅ Converted snapshot to workspace:`);\n console.log(` 📁 ${workspacePath}`);\n \n const workspace = WorkspaceCLI.readWorkspace(workspacePath);\n console.log(` 📄 ${workspace.files.length} files created`);\n } catch (error) {\n console.error('❌ Error:', error.message);\n process.exit(1);\n }\n });\n\nprogram\n .command('workspace-to-snapshot')\n .description('Convert workspace directory to snapshot file')\n .argument('', 'Path to workspace directory')\n .option('-o, --output ', 'Output snapshot file path')\n .action((workspacePath, options) => {\n try {\n const snapshotPath = WorkspaceCLI.convertWorkspaceToSnapshot(workspacePath, options.output);\n console.log(`✅ Converted workspace to snapshot:`);\n console.log(` 📄 ${snapshotPath}`);\n \n const snapshot = WorkspaceCLI.fromSnapshot(snapshotPath);\n console.log(` 📁 ${snapshot.files.length} files archived`);\n } catch (error) {\n console.error('❌ Error:', error.message);\n process.exit(1);\n }\n });\n\nprogram\n .command('show')\n .description('Display snapshot or workspace contents')\n .argument('', 'Path to snapshot file or workspace directory')\n .option('--show-tree', 'Show file tree (for workspaces)')\n .option('--show-tree-sitter-ast', 'Show Tree-sitter AST for each fish file (for workspaces)')\n .option('--no-color', 'Disable color output for Tree-sitter AST')\n .action(async (inputPath, options) => {\n try {\n if (inputPath.endsWith('.snapshot')) {\n const snapshot = WorkspaceCLI.fromSnapshot(inputPath);\n console.log(`📷 Snapshot: ${snapshot.name}`);\n console.log(`📄 Files: ${snapshot.files.length}`);\n \n snapshot.files.forEach(file => {\n console.log(` ${file.relativePath}`);\n });\n } else {\n const workspace = WorkspaceCLI.readWorkspace(inputPath);\n console.log(`📁 Workspace: ${workspace.path}`);\n console.log(`📄 Files: ${workspace.files.length}`);\n \n workspace.files.forEach(file => {\n console.log(` ${file}`);\n });\n \n if (options.showTree) {\n console.log('\\n🌳 File tree:');\n console.log(WorkspaceCLI.showFileTree(workspace.path));\n }\n \n if (options.showTreeSitterAst) {\n console.log('\\n🌳 Tree-sitter AST:');\n const useColors = !options.noColor;\n await WorkspaceCLI.showTreeSitterAST(inputPath, useColors);\n }\n }\n } catch (error) {\n console.error('❌ Error:', error.message);\n process.exit(1);\n }\n });\n\n// Handle help and completions like the build script\nif (process.argv.includes('--help') || process.argv.includes('-h')) {\n program.outputHelp();\n process.stdout.write(`\\nExamples:\\n`);\n process.stdout.write(` $ yarn sh:workspace-cli show tests/workspaces/workspace_1 --show-tree-sitter-ast\\n`);\n process.stdout.write(` shows each tree-sitter tree for file in workspaces/workspace_1\\n\\n`);\n process.stdout.write(` $ yarn sh:workspace-cli snapshot-to-workspace tests/workspaces/snapshot_comprehensive_test.snapshot \\n`);\n process.stdout.write(` convert snapshot workspace to actual file workspace\\n\\n`);\n process.stdout.write(` $ yarn sh:workspace-cli show tests/workspaces/workspace_1 --show-tree \\n`);\n process.stdout.write(` shows file tree for workspace\\n\\n`);\n process.exit(0);\n}\n\nif (process.argv.includes('--completions') || process.argv.includes('-c')) {\n generateFishCompletions();\n process.exit(0);\n}\n\nprogram.parse();\n"
},
{
"path": "src/analyze.ts",
"content": "import * as LSP from 'vscode-languageserver';\nimport { DocumentUri, Hover, Location, Position, SymbolKind, URI, WorkDoneProgressReporter, WorkspaceSymbol } from 'vscode-languageserver';\nimport * as Parser from 'web-tree-sitter';\nimport { SyntaxNode, Tree } from 'web-tree-sitter';\nimport { dirname } from 'path';\nimport { config } from './config';\nimport { documents, LspDocument } from './document';\nimport { logger } from './logger';\nimport { isArgparseVariableDefinitionName } from './parsing/argparse';\nimport { CompletionSymbol, isCompletionCommandDefinition, isCompletionSymbol, processCompletion } from './parsing/complete';\nimport { createSourceResources, getExpandedSourcedFilenameNode, isSourceCommandArgumentName, isSourceCommandWithArgument, symbolsFromResource } from './parsing/source';\nimport { filterFirstPerScopeSymbol, FishSymbol, processNestedTree } from './parsing/symbol';\nimport { getImplementation } from './references';\nimport { execCommandLocations } from './utils/exec';\nimport { SyncFileHelper } from './utils/file-operations';\nimport { flattenNested, iterateNested } from './utils/flatten';\nimport { findParentCommand, findParentFunction, isAliasDefinitionName, isCommand, isCommandName, isOption, isTopLevelDefinition, isExportVariableDefinitionName } from './utils/node-types';\nimport { pathToUri, symbolKindToString, uriToPath } from './utils/translation';\nimport { containsRange, getChildNodes, getNamedChildNodes, getRange, isPositionAfter, isPositionWithinRange, namedNodesGen, nodesGen, precedesRange } from './utils/tree-sitter';\nimport { Workspace } from './utils/workspace';\nimport { workspaceManager } from './utils/workspace-manager';\nimport { initializeParser } from './parser';\nimport { BufferedAsyncDiagnosticCache } from './diagnostics/buffered-async-cache';\nimport { env } from 'src/utils/env-manager';\n\n/*************************************************************/\n/* ts-doc type imports for links to other files here */\n/*************************************************************/\n\n// eslint-disable-next-line @typescript-eslint/no-unused-vars\nimport type { FishServer } from './server'; // @ts-ignore\n\n/*************************************************************/\n\n/**\n * Type of AnalyzedDocument, either 'partial' or 'full'.\n * - 'partial' documents do not have all properties computed,\n * - 'full' documents have all properties computed.\n *\n * @see {@link AnalyzedDocument#isPartial()} check if the document is partially parsed.\n * @see {@link AnalyzedDocument#isFull()} check if the document is fully parsed.\n *\n * @see {@link AnalyzedDocument#ensureParsed()} convert any partial documents to full ones and update {@link analyzer.cache}.\n */\nexport type AnalyzedDocumentType = 'partial' | 'full';\n\n/**\n * Specialized type of AnalyzedDocument that guarantees all the properties\n * are present so that consumers can avoid null checks once they have already\n * ensured the document is fully analyzed.\n *\n * This type will be returned from the `AnalyzedDocument.ensureParsed()` method,\n * which makes sure any partial documents are fully computed and updated.\n * @see {@link AnalyzedDocument#ensureParsed()}\n */\nexport type EnsuredAnalyzeDocument = Required & { root: SyntaxNode; tree: Tree; type: 'full'; };\n\n/**\n * AnalyzedDocument items are created in three public methods of the Analyzer class:\n * - analyze()\n * - analyzePath()\n * - analyzePartial()\n *\n * A partial AnalyzeDocument will not have the documentSymbols computed, because we\n * don't expect there to be global definitions in the document (based off of the\n * uri. i.e., $__fish_config_dir/completions/*.fish). Partial AnalyzeDocuments are\n * used to greatly reduce the overhead required for background indexing of large\n * workspaces.\n *\n * Use the AnalyzeDocument namespace to create `AnalyzedDocument` items.\n */\nexport class AnalyzedDocument {\n /**\n * private constructor to enforce the use of static creation methods.\n * @see {@link AnalyzedDocument.create()} for usage.\n *\n * @param document The LspDocument that was analyzed.\n * @param documentSymbols A nested array of FishSymbols, representing the symbols in the document.\n * @param flatSymbols A flat array of FishSymbols, representing all symbols in the document.\n * @param tree A tree that has been parsed by web-tree-sitter\n * @param root root node of a SyntaxTree\n * @param commandNodes A flat array of every command used in this document\n * @param sourceNodes All the `source some_file_path` nodes in a document, scoping is not considered.\n * However, the nodes can be filtered to consider scoping at a later time.\n * @param type If the document has been fully analyzed, or only partially.\n *\n * @returns An instance of AnalyzedDocument.\n */\n private constructor(\n /**\n * The LspDocument that was analyzed.\n */\n public document: LspDocument,\n /**\n * A nested array of FishSymbols, representing the symbols in the document.\n */\n public documentSymbols: FishSymbol[] = [],\n\n /**\n * A flat array of FishSymbols, representing all symbols in the document.\n */\n public flatSymbols: FishSymbol[] = [],\n\n /**\n * A tree that has been parsed by web-tree-sitter\n */\n public tree?: Parser.Tree,\n /**\n * root node of a SyntaxTree\n */\n public root?: Parser.SyntaxNode,\n /**\n * A flat array of every command used in this document\n */\n public commandNodes: SyntaxNode[] = [],\n /**\n * All the `source some_file_path` nodes in a document, scoping is not considered.\n * However, the nodes can be filtered to consider scoping at a later time.\n */\n public sourceNodes: SyntaxNode[] = [],\n /**\n * If the document has been fully analyzed, or only partially.\n */\n private type: AnalyzedDocumentType = tree ? 'full' : 'partial',\n ) {\n if (tree) this.root = tree.rootNode || undefined;\n }\n\n /**\n * Static method to create an AnalyzedDocument. If passed a tree, it will\n * be considered a fully parsed document. Otherwise, it will be considered a partial document.\n *\n * @see {@link AnalyzedDocument.createFull()} {@link AnalyzedDocument.createPartial()}\n *\n * @param document The LspDocument that was analyzed.\n * @param documentSymbols A nested array of FishSymbols, representing the symbols in the document.\n * @param tree A tree that has been parsed by web-tree-sitter\n * @param root root node of a SyntaxTree\n * @param commandNodes A flat array of every command used in this document\n * @param sourceNodes All the `source some_file_path` nodes in a document, scoping is not considered.\n *\n * @returns An instance of AnalyzedDocument returned from createdFull() or createdPartial().\n */\n private static create(\n document: LspDocument,\n documentSymbols: FishSymbol[] = [],\n flatSymbols: FishSymbol[] = [],\n tree: Parser.Tree | undefined = undefined,\n root: Parser.SyntaxNode | undefined = undefined,\n commandNodes: SyntaxNode[] = [],\n sourceNodes: SyntaxNode[] = [],\n ): AnalyzedDocument {\n return new AnalyzedDocument(\n document,\n documentSymbols,\n flatSymbols,\n tree,\n root || tree?.rootNode,\n commandNodes,\n sourceNodes,\n tree ? 'full' : 'partial',\n );\n }\n\n /**\n * Static method to create a fully parsed AnalyzedDocument.\n * Extracts both the commandNodes and sourceNodes from the tree provided.\n *\n * @see {@link AnalyzedDocument.create()} which handles initialization internally.\n *\n * @param document The LspDocument that was analyzed.\n * @param documentSymbols A nested array of FishSymbols, representing the symbols in the document.\n * @param tree A tree that has been parsed by web-tree-sitter\n *\n * @returns An instance of AnalyzedDocument, with all properties populated.\n */\n public static createFull(\n document: LspDocument,\n documentSymbols: FishSymbol[],\n tree: Parser.Tree,\n ): AnalyzedDocument {\n const commandNodes: SyntaxNode[] = [];\n const sourceNodes: SyntaxNode[] = [];\n tree.rootNode.descendantsOfType('command').forEach(node => {\n if (isSourceCommandWithArgument(node)) sourceNodes.push(node.child(1)!);\n commandNodes.push(node);\n });\n return new AnalyzedDocument(\n document,\n documentSymbols,\n flattenNested(...documentSymbols),\n tree,\n tree.rootNode,\n commandNodes,\n sourceNodes,\n 'full',\n );\n }\n\n /**\n * Static method to create a partially parsed AnalyzedDocument. Partial documents\n * do not compute any expensive properties such as documentSymbols, commandNodes, or sourceNodes.\n *\n * This saves significant time during initial workspace analysis, especially for large workspaces\n * by assuming certain documents (such as those in completions directories) do not contain\n * global `FishSymbol[]` definitions. We can then lazily compute partial documents\n * by checking if opened/changed documents had references to lazily loaded documents.\n *\n * @see {@link AnalyzedDocument.create()} which handles initialization internally.\n * @see {@link AnalyzedDocument#ensureParsed()} to fully parse a partial document when needed.\n *\n * @param document The LspDocument that was analyzed.\n *\n * @returns An instance of AnalyzedDocument, with only the document property populated.\n */\n public static createPartial(document: LspDocument): AnalyzedDocument {\n return AnalyzedDocument.create(document);\n }\n\n /**\n * Check if the AnalyzedDocument is partial (not fully parsed).\n * @see {@link AnalyzedDocument#ensureParsed()} which will convert a partial document to a full one.\n * @returns {boolean} True if the AnalyzedDocument is partial, false otherwise.\n */\n public isPartial(): boolean {\n return this.type === 'partial';\n }\n\n /**\n * Check if the AnalyzedDocument is fully parsed.\n * @returns {boolean} True if the AnalyzedDocument is full, false otherwise.\n */\n public isFull(): boolean {\n return this.type === 'full';\n }\n\n public ensureParsed(): EnsuredAnalyzeDocument {\n if (this.isPartial()) {\n const fullDocument = analyzer.analyze(this.document);\n // Update this instance's properties in-place\n this.documentSymbols = fullDocument.documentSymbols;\n this.flatSymbols = fullDocument.flatSymbols;\n this.tree = fullDocument.tree;\n this.root = fullDocument.root;\n this.commandNodes = fullDocument.commandNodes;\n this.sourceNodes = fullDocument.sourceNodes;\n this.type = 'full';\n\n // Update the cache with the fully parsed document\n analyzer.cache.setDocument(this.document.uri, this);\n return this as EnsuredAnalyzeDocument;\n }\n return this as EnsuredAnalyzeDocument;\n }\n}\n\n/**\n * Call `await analyzer.initialize()` to create an instance of the Analyzer class.\n * This way we avoid instantiating the parser, and passing it to each analyzer\n * instance that we create (common test pattern). Also, by initializing the\n * analyzer globally, we can import it to any procedure that needs access\n * to the analyzer.\n *\n * The analyzer stores and computes our symbols, from the tree-sitter AST and\n * caches the results in AnalyzedDocument[] items.\n */\nexport let analyzer: Analyzer;\n\n/***\n * Handles analysis of documents and caching their symbols.\n *\n * Lots of server functionality is implemented here. Including, but not limited to:\n * - tree sitter parsing\n * - document analysis and caching\n * - workspace/document symbol searching\n * - background analysis performed on startup\n *\n * Requires a tree-sitter Parser instance to be initialized for usage.\n */\nexport class Analyzer {\n /**\n * The cached documents from all workspaces\n * - keys are the document uris\n * - values are the AnalyzedDocument objects\n */\n public cache: AnalyzedDocumentCache = new AnalyzedDocumentCache();\n /**\n * All of the global symbols throughout all workspaces in the server.\n * Methods that use this cache might try to limit symbols to a single workspace.\n *\n * The `globalSymbols.map` is a used to cache the symbols for quick access\n * - keys are the symbol names\n * - values are the FishSymbol objects\n */\n public globalSymbols: GlobalDefinitionCache = new GlobalDefinitionCache();\n\n public started = false;\n\n public diagnostics: BufferedAsyncDiagnosticCache = new BufferedAsyncDiagnosticCache();\n\n constructor(public parser: Parser) { }\n\n /**\n * The method that is used to instantiate the **singleton** {@link analyzer}, to avoid\n * dependency injecting the analyzer in every utility that might need it.\n *\n * This method can be called during the `connection.onInitialize()` in the server,\n * or {@link https://vitest.dev/ | vite.beforeAll()} in a test-suite.\n *\n * @example\n * ```typescript\n * // file: ./tests/some-test-file.test.ts\n * import { Analyzer, analyzer } from '../src/analyze';\n *\n * // Initialize the `analyzer` singleton through the `Analyzer.initialize()`\n * // method to make it available throughout testing. This helps keep tests\n * // consistent with the analysis functionality used throughout entire server.\n *\n * describe('test suite', () => {\n * // Make sure the analyzer is initialized before any tests run\n * beforeAll(async () => {\n * await Analyzer.initialize();\n * // analyzer.parser exists if needed\n * // we can also use analyzer anywhere now in the test file\n * });\n * it('test 1', () => {\n * const result1 = analyzer.analyzePath('/path/to/file.fish');\n * const result2 = analyzer.analyze(result1.document);\n * expect(result1.document.uri).toBe(result2.document.uri);\n * });\n * it('test 2', () => {\n * const tree = analyzer.parser.parse('fish --help')\n * const { rootNode } = tree;\n * expect(rootNode).toBeDefined();\n * });\n * // ...\n * });\n * ```\n *\n * ___\n *\n * It is okay to use the {@link Analyzer} returned for testing purposes, however for\n * consistency throughout source code, please use the exported {@link analyzer} variable.\n *\n * @returns Promise The initialized Analyzer instance (recommended to directly import {@link analyzer}).\n */\n public static async initialize(): Promise {\n const parser = await initializeParser();\n analyzer = new Analyzer(parser);\n analyzer.started = true;\n return analyzer;\n }\n\n /**\n * Perform full analysis on a LspDocument to build a AnalyzedDocument containing\n * useful information about the document. It will also add the information to both\n * the cache of AnalyzedDocuments and the global symbols cache.\n *\n * @param document The {@link LspDocument} to analyze.\n * @returns An {@linkcode AnalyzedDocument} object.\n */\n public analyze(document: LspDocument): AnalyzedDocument {\n const analyzedDocument = this.getAnalyzedDocument(document);\n this.cache.setDocument(document.uri, analyzedDocument);\n\n // Remove old global symbols for this document before adding new ones\n this.globalSymbols.removeSymbolsByUri(document.uri);\n\n // Add new global symbols\n for (const symbol of iterateNested(...analyzedDocument.documentSymbols)) {\n if (symbol.isGlobal()) this.globalSymbols.add(symbol);\n }\n return analyzedDocument;\n }\n\n /**\n * Remove all global symbols for a document (used when document is closed or deleted)\n */\n public removeDocumentSymbols(uri: string): void {\n this.globalSymbols.removeSymbolsByUri(uri);\n this.cache.clear(uri);\n }\n\n /**\n * @param uri the DocumentUri of the document that needs resolution\n * @returns AnalyzedDocument {@link @AnalyzedDocument} or undefined if the file could not be found.\n */\n public analyzeUri(uri: DocumentUri): AnalyzedDocument | undefined {\n const document = documents.get(uri) || SyncFileHelper.loadDocumentSync(uriToPath(uri));\n if (!document) {\n logger.warning(`analyzer.analyzePath: ${uri} not found`);\n return undefined;\n }\n return this.analyze(document);\n }\n\n /**\n * @summary\n * Takes a path to a file and turns it into a LspDocument, to then be analyzed\n * and cached. This is useful for testing purposes, or for the rare occasion that\n * we need to analyze a file that is not yet a LspDocument.\n *\n * @param filepath The local machine's path to the document that needs resolution\n * @returns AnalyzedDocument {@link @AnalyzedDocument} or undefined if the file could not be found.\n */\n public analyzePath(rawFilePath: string): AnalyzedDocument | undefined {\n const path = uriToPath(rawFilePath);\n const document = SyncFileHelper.loadDocumentSync(path);\n if (!document) {\n logger.warning(`analyzer.analyzePath: ${path} not found`);\n return undefined;\n }\n return this.analyze(document);\n }\n\n /**\n * @public\n * Use on documents where we can assume the document nodes aren't important.\n * This could mainly be summarized as any file in `$fish_complete_path/*.fish`\n * This greatly reduces the time it takes for huge workspaces to be analyzed,\n * by only retrieving the bare minimum of information required from completion\n * documents. Since completion documents are fully parsed, only once a request\n * is made that requires a completion document, we are able to avoid building\n * their document symbols here. Conversely, this means that if we were to use\n * this method instead of the full `analyze()` method, any requests that need\n * symbols from the document will not be able to retrieve them.\n *\n * @see {@link AnalyzedDocument#ensureParsed()} convert a partial document to a full one\n * and update the {@link analyzer.cache} with the newly computed full document.\n *\n * @param document The {@link LspDocument} to analyze.\n * @returns partial result of {@link AnalyzedDocument.createPartial()} with no computed\n * properties set, which we use {@link FishServer#didChangeTextDocument()}\n * to later ensure any reachable symbols are computed local to the open document.\n */\n public analyzePartial(document: LspDocument): AnalyzedDocument {\n const analyzedDocument = AnalyzedDocument.createPartial(document);\n this.cache.setDocument(document.uri, analyzedDocument);\n return analyzedDocument;\n }\n\n /**\n * @private\n *\n * Helper method to get the AnalyzedDocument. Retrieves the parsed\n * AST from {@link https://github.com/tree-sitter/tree-sitter/tree/master/lib/binding_web | web-tree-sitter's} {@link Parser},\n *\n * - processes the {@link DocumentSymbol},\n * - stores the commands used in the document,\n * - collects all the sourced command {@link SyntaxNode}'s arguments\n * **(potential file paths)**\n *\n * @param LspDocument The {@link LspDocument} to analyze.\n * @returns An {@link AnalyzedDocument} object.\n */\n private getAnalyzedDocument(document: LspDocument): AnalyzedDocument {\n const tree = this.parser.parse(document.getText());\n const documentSymbols = processNestedTree(document, tree.rootNode);\n return AnalyzedDocument.createFull(document, documentSymbols, tree);\n }\n\n /**\n * Analyze a workspace and all its documents.\n * Documents that are already analyzed will be skipped.\n * For documents that are autoloaded completions, we only perform a partial analysis.\n * This method also reports progress to the provided WorkDoneProgressReporter.\n *\n * @param workspace The workspace to analyze.\n * @param progress Optional WorkDoneProgressReporter to report progress.\n * @param callbackfn Optional callback function to report messages.\n */\n public async analyzeWorkspace(\n workspace: Workspace,\n progress: WorkDoneProgressReporter | undefined = undefined,\n callbackfn: (text: string) => void = (text: string) => logger.log(`analyzer.analyzerWorkspace(${workspace.name})`, text),\n ) {\n const startTime = performance.now();\n if (workspace.isAnalyzed()) {\n callbackfn(`[fish-lsp] workspace ${workspace.name} already analyzed`);\n progress?.done();\n return { count: 0, workspace, duration: '0.00' };\n }\n\n // progress?.begin(workspace.name, 0, 'Analyzing workspace', true);\n const docs = workspace.pendingDocuments();\n const maxSize = Math.min(docs.length, config.fish_lsp_max_background_files);\n const currentDocuments = workspace.pendingDocuments().slice(0, maxSize);\n\n // Helper function to delay execution\n const delay = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));\n\n // Calculate adaptive delay and batch size based on document count\n const BATCH_SIZE = Math.max(1, Math.floor(currentDocuments.length / 20));\n const UPDATE_DELAY = currentDocuments.length > 100 ? 10 : 25; // Shorter delay for large sets\n\n let lastUpdateTime = 0;\n const MIN_UPDATE_INTERVAL = 15; // Minimum ms between visual updates\n\n currentDocuments.forEach(async (doc, idx) => {\n try {\n if (doc.getAutoloadType() === 'completions') {\n this.analyzePartial(doc);\n } else {\n this.analyze(doc);\n }\n workspace.uris.markIndexed(doc.uri);\n const reportPercent = Math.ceil(idx / maxSize * 100);\n progress?.report(reportPercent, `Analyzing ${idx}/${docs.length} files`);\n } catch (err) {\n logger.log(`[fish-lsp] ERROR analyzing workspace '${workspace.name}' (${err?.toString() || ''})`);\n }\n\n const currentTime = performance.now();\n const isLastItem = idx === currentDocuments.length - 1;\n const isBatchEnd = idx % BATCH_SIZE === BATCH_SIZE - 1;\n const timeToUpdate = currentTime - lastUpdateTime > MIN_UPDATE_INTERVAL;\n\n if (isLastItem || isBatchEnd && timeToUpdate) {\n const percentage = Math.ceil((idx + 1) / maxSize * 100);\n progress?.report(`${percentage}% Analyzing ${idx + 1}/${maxSize} ${maxSize > 1 ? 'documents' : 'document'}`);\n lastUpdateTime = currentTime;\n\n // Add a small delay for visual perception\n await delay(UPDATE_DELAY);\n }\n });\n progress?.done();\n const endTime = performance.now();\n const duration = ((endTime - startTime) / 1000).toFixed(2); // Convert to seconds with 2 decimal places\n const count = currentDocuments.length;\n const message = `Analyzed ${count} document${count > 1 ? 's' : ''} in ${duration}s`;\n callbackfn(message);\n return {\n count: currentDocuments.length,\n workspace: workspace,\n duration,\n };\n }\n\n /**\n * Return the first FishSymbol seen that matches is defined at the location passed in\n */\n public getSymbolAtLocation(location: Location): FishSymbol | undefined {\n const symbols = this.cache.getFlatDocumentSymbols(location.uri);\n return symbols.find((symbol) => symbol.equalsLocation(location));\n }\n\n /**\n * Return the first FishSymbol seen that could be defined by the given position.\n */\n public findDocumentSymbol(\n document: LspDocument,\n position: Position,\n ): FishSymbol | undefined {\n const symbols = flattenNested(...this.cache.getDocumentSymbols(document.uri));\n return symbols.find((symbol) => {\n return isPositionWithinRange(position, symbol.selectionRange);\n });\n }\n\n /**\n * Return all FishSymbols seen that could be defined by the given position.\n */\n public findDocumentSymbols(\n document: LspDocument,\n position: Position,\n ): FishSymbol[] {\n const symbols = flattenNested(...this.cache.getDocumentSymbols(document.uri));\n return symbols.filter((symbol) => {\n return isPositionWithinRange(position, symbol.selectionRange);\n });\n }\n\n /**\n * Search through all the documents in the cache, and return the first symbol found\n * that matches the callback function.\n */\n public findSymbol(\n callbackfn: (symbol: FishSymbol, doc?: LspDocument) => boolean,\n ) {\n for (const uri of this.getIterableUris()) {\n const symbols = this.cache.getFlatDocumentSymbols(uri);\n const document = this.cache.getDocument(uri)?.document;\n const symbol = symbols.find(s => callbackfn(s, document));\n if (symbol) {\n return symbol;\n }\n }\n return undefined;\n }\n\n /**\n * Search through all the documents in the cache, and return all symbols found\n */\n public findSymbols(\n callbackfn: (symbol: FishSymbol, doc?: LspDocument) => boolean,\n ): FishSymbol[] {\n const symbols: FishSymbol[] = [];\n for (const uri of this.getIterableUris()) {\n const document = this.cache.getDocument(uri)?.document;\n const symbols = this.getFlatDocumentSymbols(document!.uri);\n const newSymbols = symbols.filter(s => callbackfn(s, document));\n if (newSymbols) {\n symbols.push(...newSymbols);\n }\n }\n return symbols;\n }\n\n /**\n * Search through all the documents in the cache, and return the first node found\n */\n public findNode(\n callbackfn: (n: SyntaxNode, document?: LspDocument) => boolean,\n ): SyntaxNode | undefined {\n const uris = this.cache.uris();\n for (const uri of uris) {\n const root = this.cache.getRootNode(uri);\n const document = this.cache.getDocument(uri)!.document;\n if (!root || !document) continue;\n const node = getChildNodes(root).find((n) => callbackfn(n, document));\n if (node) {\n return node;\n }\n }\n return undefined;\n }\n\n /**\n * Search through all the documents in the cache, and return all nodes found (with their uris)\n */\n public findNodes(\n callbackfn: (node: SyntaxNode, document: LspDocument) => boolean,\n // useCurrentWorkspace: boolean = true,\n ): {\n uri: string;\n nodes: SyntaxNode[];\n }[] {\n const result: { uri: string; nodes: SyntaxNode[]; }[] = [];\n for (const uri of this.getIterableUris()) {\n const root = this.cache.getRootNode(uri);\n const document = this.cache.getDocument(uri)?.document;\n if (!root || !document) continue;\n const nodes = getChildNodes(root).filter((node) => callbackfn(node, document));\n if (nodes.length > 0) {\n result.push({ uri: document.uri, nodes });\n }\n }\n return result;\n }\n\n /**\n * A generator function that yields all the documents in the workspace.\n */\n public * findDocumentsGen(): Generator {\n for (const uri of this.getIterableUris()) {\n const document = this.cache.getDocument(uri)?.document;\n if (document) {\n yield document;\n }\n }\n }\n\n /**\n * A generator function that yields all the symbols in the workspace, per document\n * The symbols yielded are flattened FishSymbols (NOT nested).\n */\n public * findSymbolsGen(): Generator<{ document: LspDocument; symbols: FishSymbol[]; }> {\n for (const uri of this.getIterableUris()) {\n const symbols = this.cache.getFlatDocumentSymbols(uri);\n const document = this.cache.getDocument(uri)?.document;\n if (!document || !symbols) continue;\n yield { document, symbols };\n }\n }\n\n /**\n * A generator function that yields all the nodes in the workspace, per document.\n * The nodes yielded are using the `this.getNodes()` method, which returns the cached\n * nodes for the document.\n */\n public * findNodesGen(): Generator<{ document: LspDocument; nodes: Generator; }> {\n for (const uri of this.getIterableUris()) {\n const root = this.cache.getRootNode(uri);\n const document = this.cache.getDocument(uri)?.document;\n if (!root || !document) continue;\n yield { document, nodes: this.nodesGen(document.uri).nodes };\n }\n }\n\n /**\n * Collect all the global symbols in the workspace, and the document symbols usable\n * at the requests position. DocumentSymbols that are not in the position's scope are\n * excluded from the result array of FishSymbols.\n *\n * This method is mostly notably used for providing the symbols in\n * `server.onCompletion()` requests.\n *\n * @param document The LspDocument to search in\n * @param position The position to search at\n * @returns {FishSymbol[]} A flat array of FishSymbols that are usable at the given position\n */\n public allSymbolsAccessibleAtPosition(document: LspDocument, position: Position): FishSymbol[] {\n // Set to avoid duplicate symbols\n const symbolNames: Set = new Set();\n // add the local symbols\n const symbols = flattenNested(...this.cache.getDocumentSymbols(document.uri))\n .filter((symbol) => symbol.scope.containsPosition(position));\n symbols.forEach((symbol) => symbolNames.add(symbol.name));\n // add the sourced symbols\n const sourcedUris = this.collectReachableSources(document.uri, position);\n for (const sourcedUri of Array.from(sourcedUris)) {\n const sourcedSymbols = this.cache.getFlatDocumentSymbols(sourcedUri)\n .filter(s =>\n !symbolNames.has(s.name)\n && (s.isGlobal() || s.isRootLevel())\n && s.uri !== document.uri,\n );\n symbols.push(...sourcedSymbols);\n sourcedSymbols.forEach((symbol) => symbolNames.add(symbol.name));\n }\n // add the global symbols\n for (const globalSymbol of this.globalSymbols.allSymbols) {\n // skip any symbols that are already in the result so that\n // next conditionals don't have to consider duplicate symbols\n if (symbolNames.has(globalSymbol.name)) continue;\n // any global symbol not in the document\n if (globalSymbol.uri !== document.uri) {\n symbols.push(globalSymbol);\n symbolNames.add(globalSymbol.name);\n // any symbol in the document that is globally scoped\n } else if (globalSymbol.uri === document.uri) {\n symbols.push(globalSymbol);\n symbolNames.add(globalSymbol.name);\n }\n }\n return symbols;\n }\n\n /**\n * method that returns all the workspaceSymbols that are in the same scope as the given\n * shell\n * @returns {WorkspaceSymbol[]} array of all symbols\n */\n public getWorkspaceSymbols(query: string = ''): WorkspaceSymbol[] {\n const workspace = workspaceManager.current;\n logger.log({ searching: workspace?.path, query });\n return this.globalSymbols.allSymbols\n .filter(symbol => workspace?.contains(symbol.uri) || symbol.uri === workspace?.uri)\n .map((s) => s.toWorkspaceSymbol())\n .filter((symbol: WorkspaceSymbol) => {\n return symbol.name.startsWith(query);\n });\n }\n\n /**\n * Utility function to get the definitions of a symbol at a given position.\n */\n private getDefinitionHelper(document: LspDocument, position: Position): FishSymbol[] {\n const symbols: FishSymbol[] = [];\n const word = this.wordAtPoint(document.uri, position.line, position.character);\n const node = this.nodeAtPoint(document.uri, position.line, position.character);\n if (!word || !node) return [];\n\n // First check local symbols\n const localSymbols = this.getFlatDocumentSymbols(document.uri);\n const localSymbol = localSymbols.find((s) => {\n return s.name === word && containsRange(s.selectionRange, getRange(node));\n });\n if (localSymbol) {\n symbols.push(localSymbol);\n } else {\n const toAdd: FishSymbol[] = localSymbols.filter((s) => {\n const variableBefore = s.kind === SymbolKind.Variable ? precedesRange(s.selectionRange, getRange(node)) : true;\n return (\n s.name === word\n && containsRange(getRange(s.scope.scopeNode), getRange(node))\n && variableBefore\n );\n });\n symbols.push(...toAdd);\n }\n\n // If no local symbols found, check sourced symbols\n if (!symbols.length) {\n const allAccessibleSymbols = this.allSymbolsAccessibleAtPosition(document, position);\n const sourcedSymbols = allAccessibleSymbols.filter(s =>\n s.name === word && s.uri !== document.uri,\n );\n symbols.push(...sourcedSymbols);\n }\n\n // Finally, check global symbols as fallback\n if (!symbols.length) {\n symbols.push(...this.globalSymbols.find(word));\n }\n\n return symbols;\n }\n\n /**\n * Get the first definition of a position that we can find.\n * Will first retrieve {@link Analyzer#getDefinitionHelper()} to look for possible definitions.\n * Symbols found are then handled based on their node type, to ensure we return the most relevant definition.\n * If symbol exists, but doesn't match any of the special cases, we return the last symbol found.\n */\n public getDefinition(document: LspDocument, position: Position): FishSymbol | null {\n const symbols: FishSymbol[] = this.getDefinitionHelper(document, position);\n const word = this.wordAtPoint(document.uri, position.line, position.character);\n const node = this.nodeAtPoint(document.uri, position.line, position.character);\n if (node && isExportVariableDefinitionName(node)) {\n return symbols.find(s => s.name === word) || symbols.pop()!;\n }\n if (node && isAliasDefinitionName(node)) {\n return symbols.find(s => s.name === word) || symbols.pop()!;\n }\n if (node && isArgparseVariableDefinitionName(node)) {\n const atPos = this.getFlatDocumentSymbols(document.uri).findLast(s =>\n s.containsPosition(position) && s.fishKind === 'ARGPARSE',\n ) || symbols.pop()!;\n return atPos;\n }\n if (node && isCompletionSymbol(node)) {\n const completionSymbols = this.getFlatCompletionSymbols(document.uri);\n const completionSymbol = completionSymbols.find(s => s.equalsNode(node));\n if (!completionSymbol) {\n return null;\n }\n const symbol = this.findSymbol((s) => completionSymbol.equalsArgparse(s));\n if (symbol) return symbol;\n }\n if (node && isOption(node)) {\n const symbol = this.findSymbol((s) => {\n if (s.parent && s.fishKind === 'ARGPARSE') {\n return node.parent?.firstNamedChild?.text === s.parent?.name &&\n s.parent.isGlobal() &&\n node.text.startsWith(s.argparseFlag);\n }\n return false;\n });\n if (symbol) return symbol;\n }\n return symbols.pop() || null;\n }\n\n /**\n * Get all the definition locations of a position that we can find\n */\n public getDefinitionLocation(document: LspDocument, position: Position): LSP.Location[] {\n // handle source argument definition location\n const node = this.nodeAtPoint(document.uri, position.line, position.character);\n\n // check that the node (or its parent) is a `source` command argument\n if (node && isSourceCommandArgumentName(node)) {\n return this.getSourceDefinitionLocation(node, document);\n }\n if (node && node.parent && isSourceCommandArgumentName(node.parent)) {\n return this.getSourceDefinitionLocation(node.parent, document);\n }\n\n // check if we have a symbol defined at the position\n const symbol = this.getDefinition(document, position) as FishSymbol;\n if (symbol) {\n if (symbol.isEvent()) return [symbol.toLocation()];\n\n const newSymbol = filterFirstPerScopeSymbol(document.uri)\n .find((s) => s.equalDefinition(symbol));\n\n if (newSymbol) return [newSymbol.toLocation()];\n }\n if (symbol) return [symbol.toLocation()];\n\n // allow execCommandLocations to provide location for command when no other\n // definition has been found. Previously, config.fish_lsp_single_workspace_support\n // was used to prevent this case from being hit but now we always allow it.\n if (workspaceManager.current) {\n const node = this.nodeAtPoint(document.uri, position.line, position.character);\n if (node && isCommandName(node)) {\n const text = node.text.toString();\n const locations = findCommandLocations(text);\n return locations.map(({ uri }) =>\n Location.create(uri, {\n start: { line: 0, character: 0 },\n end: { line: 0, character: 0 },\n }),\n );\n }\n }\n return [];\n }\n\n /**\n * Here we can allow the user to use completion locations for the implementation.\n */\n public getImplementation(document: LspDocument, position: Position): Location[] {\n const definition = this.getDefinition(document, position);\n if (!definition) return [];\n const locations = getImplementation(document, position);\n return locations;\n }\n\n /**\n * Gets the location of the sourced file for the given source command argument name node.\n */\n private getSourceDefinitionLocation(node: SyntaxNode, document: LspDocument): LSP.Location[] {\n if (node && isSourceCommandArgumentName(node)) {\n // Get the base directory for resolving relative paths\n const fromPath = uriToPath(document.uri);\n const baseDir = dirname(fromPath);\n\n const expanded = getExpandedSourcedFilenameNode(node, baseDir) as string;\n let sourceDoc = this.getDocumentFromPath(expanded);\n if (!sourceDoc) {\n this.analyzePath(expanded); // find the filepath & analyze it\n sourceDoc = this.getDocumentFromPath(expanded); // reset the sourceDoc to new value\n }\n if (sourceDoc) {\n return [\n Location.create(sourceDoc!.uri, LSP.Range.create(0, 0, 0, 0)),\n ];\n }\n }\n return [];\n }\n\n /**\n * Get the hover from the given position in the document, if it exists.\n * This is either a symbol, a manpage, or a fish-shell shipped function.\n * Other hovers are shown are shown if this method can't find any (defined in `./hover.ts`).\n */\n public getHover(document: LspDocument, position: Position): Hover | null {\n const tree = this.getTree(document.uri);\n const node = this.nodeAtPoint(document.uri, position.line, position.character);\n\n if (!tree || !node) return null;\n\n const symbol =\n this.getDefinition(document, position) ||\n this.globalSymbols.findFirst(node.text);\n\n if (!symbol) return null;\n logger.log(`analyzer.getHover: ${symbol.name}`, {\n name: symbol.name,\n uri: symbol.uri,\n detail: symbol.detail,\n text: symbol.node.text,\n kind: symbolKindToString(symbol.kind),\n });\n return symbol.toHover();\n }\n\n /**\n * Returns the tree-sitter tree for the given documentUri.\n * If the document is not in the cache, it will cache it and return the tree.\n *\n * @NOTE: we use `documentUri` here instead of LspDocument's because it simplifies\n * testing and is more consistently available in the server.\n *\n * @param documentUri - the uri of the document to get the tree for\n * @return {Tree | undefined} - the tree for the document, or undefined if the document is not in the cache\n */\n getTree(documentUri: string): Tree | undefined {\n if (this.cache.hasUri(documentUri)) {\n const doc = this.cache.getDocument(documentUri);\n if (doc) {\n return doc.ensureParsed().tree;\n }\n }\n return this.analyzePath(uriToPath(documentUri))?.tree;\n }\n\n /**\n * gets/finds the rootNode given a DocumentUri. if cached it will return the root from the cache,\n * Otherwise it will analyze the path and return the root node, which might not be possible if the path\n * is not readable or the file does not exist.\n * @see {@link https://github.com/tree-sitter/tree-sitter/tree/master/lib/binding_web | web-tree-sitter's} {@link SyntaxNode}\n * @param documentUri - the uri of the document to get the root node for\n * @return {SyntaxNode | undefined} - the root node for the document, or undefined if the document is not in the cache\n */\n getRootNode(documentUri: string): SyntaxNode | undefined {\n if (this.cache.hasUri(documentUri)) {\n const doc = this.cache.getDocument(documentUri);\n if (doc) {\n return doc.ensureParsed().root;\n }\n }\n return this.analyzePath(uriToPath(documentUri))?.root;\n }\n\n /**\n * Returns the document from the cache. If the document is not in the cache,\n * it will return undefined.\n */\n getDocument(documentUri: string): LspDocument | undefined {\n return this.cache.getDocument(documentUri)?.document;\n }\n\n /**\n * Returns the document from the cache if the document is in the cache.\n */\n getDocumentFromPath(path: string): LspDocument | undefined {\n const uri = pathToUri(path);\n return this.getDocument(uri);\n }\n\n /**\n * Returns the FishSymbol[] array in the cache for the given documentUri.\n * The result is a nested array (tree) of FishSymbol[] items\n */\n getDocumentSymbols(documentUri: string): FishSymbol[] {\n return this.cache.getDocumentSymbols(documentUri);\n }\n\n /**\n * Returns the flat array of FishSymbol[] for the given documentUri.\n * Iterating through the result will allow you to reach every symbol in the documentUri.\n */\n getFlatDocumentSymbols(documentUri: string): FishSymbol[] {\n return this.cache.getFlatDocumentSymbols(documentUri);\n }\n\n /**\n * Returns a list of symbols similar to a DocumentSymbol array, but\n * instead of using that data type, we use our custom CompletionSymbol to define completions\n *\n * NOTE: while this method's visibility is public, it is really more of a utility\n * for the `getGlobalArgparseLocations()` function in `src/parsing/argparse.ts`\n *\n * @param documentUri - the uri of the document to get the completions for\n * @returns {CompletionSymbol[]} - an array of CompletionSymbol objects\n */\n getFlatCompletionSymbols(documentUri: string): CompletionSymbol[] {\n const doc = this.cache.getDocument(documentUri);\n if (!doc) return [];\n const { document, commandNodes } = doc;\n // get the `complete` SyntaxNode[]\n const childrenSymbols = commandNodes.filter(n => isCompletionCommandDefinition(n));\n // build the CompletionSymbol[] for the entire document\n const result: CompletionSymbol[] = [];\n for (const child of childrenSymbols) {\n result.push(...processCompletion(document, child));\n }\n return result;\n }\n\n /**\n * Returns a list of all the nodes in the document.\n */\n public nodesGen(documentUri: string): {\n nodes: Generator;\n namedNodes: Generator;\n } {\n const document = this.cache.getDocument(documentUri)?.document;\n if (!document) {\n return { nodes: (function* () { })(), namedNodes: (function* () { })() }; // Return an empty generator if the document is not found\n }\n const root = this.getRootNode(documentUri);\n if (!root) {\n return { nodes: (function* () { })(), namedNodes: (function* () { })() }; // Return an empty generator if the root node is not found\n }\n return {\n nodes: nodesGen(root),\n namedNodes: namedNodesGen(root),\n };\n }\n\n /**\n * Returns a list of all the nodes in the document.\n */\n public getNodes(documentUri: string): SyntaxNode[] {\n const document = this.cache.getDocument(documentUri)?.document;\n if (!document) {\n return [];\n }\n return getChildNodes(this.parser.parse(document.getText()).rootNode);\n }\n\n /**\n * Returns a list of all the NAMED nodes in the document.\n */\n public getNamedNodes(documentUri: string): SyntaxNode[] {\n const document = this.cache.getDocument(documentUri)?.document;\n if (!document) {\n return [];\n }\n return getNamedChildNodes(this.parser.parse(document.getText()).rootNode);\n }\n\n /**\n * Utility to collect all the sources in the input documentUri, or if specified\n * it will only collect the included sources from the sources parameter\n * @param documentUri - the uri of the document to collect sources from\n * @param sources - the sources to collect from (optional set to narrow results)\n * @returns {Set} - a flat set of all the sourceUri's reachable from the input sources\n */\n public collectSources(\n documentUri: string,\n sources = this.cache.getSources(documentUri),\n ): Set {\n const visited = new Set();\n const collectionStack: string[] = Array.from(sources);\n while (collectionStack.length > 0) {\n const source = collectionStack.pop()!;\n if (visited.has(source)) continue;\n visited.add(source);\n if (SyncFileHelper.isDirectory(uriToPath(source))) continue;\n if (!SyncFileHelper.isFile(uriToPath(source))) continue;\n\n const cahedSourceDoc = this.cache.hasUri(source)\n ? this.cache.getDocument(source) as AnalyzedDocument\n : this.analyzePath(uriToPath(source)) as AnalyzedDocument;\n if (!cahedSourceDoc) continue;\n const sourced = this.cache.getSources(cahedSourceDoc.document.uri);\n collectionStack.push(...Array.from(sourced));\n }\n return visited;\n }\n\n /**\n * Collects all the sourceUri's that are reachable from the given documentUri at Position\n * @param documentUri - the uri of the document to collect sources from\n * @param position - the position to collect sources from\n * @returns {Set} - a set of all the sourceUri's in the document before the position\n */\n public collectReachableSources(documentUri: string, position: Position): Set {\n const currentNode = this.nodeAtPoint(documentUri, position.line, position.character);\n let currentParent: SyntaxNode | null;\n if (currentNode) currentParent = findParentFunction(currentNode);\n const sourceNodes = this.cache.getSourceNodes(documentUri)\n .filter(node => {\n if (isTopLevelDefinition(node) && isPositionAfter(getRange(node).start, position)) {\n return true;\n }\n const parentFunction = findParentFunction(node);\n if (currentParent && parentFunction?.equals(currentParent) && isPositionAfter(getRange(node).start, position)) {\n return true;\n }\n return false;\n });\n const sources = new Set();\n\n // Get the base directory for resolving relative paths\n const fromPath = uriToPath(documentUri);\n const baseDir = dirname(fromPath);\n\n for (const node of sourceNodes) {\n const sourced = getExpandedSourcedFilenameNode(node, baseDir);\n if (sourced) {\n sources.add(pathToUri(sourced));\n }\n }\n return this.collectSources(documentUri, sources);\n }\n\n /**\n * Collects all the sourceUri's that are in the documentUri\n * @param documentUri - the uri of the document to collect sources from\n * @returns {Set} - a set of all the sourceUri's in the document\n */\n public collectAllSources(documentUri: string): Set {\n const allSources = this.collectSources(documentUri);\n for (const source of Array.from(allSources)) {\n const sourceDoc = this.cache.getDocument(source);\n if (!sourceDoc) {\n this.analyzePath(source);\n }\n }\n return allSources;\n }\n\n /**\n * Collects all sourced symbols for a document, including symbols from all reachable source files.\n * This is used for document symbols to include sourced functions and variables.\n * @param documentUri - the uri of the document to collect sourced symbols for\n * @returns {FishSymbol[]} - array of all sourced symbols (functions, variables) that should be visible\n */\n public collectSourcedSymbols(documentUri: string): FishSymbol[] {\n const sourcedSymbols: FishSymbol[] = [];\n const uniqueNames = new Set();\n\n // Get all sourced files reachable from this document\n const sourcedUris = this.collectAllSources(documentUri);\n\n for (const sourcedUri of sourcedUris) {\n if (sourcedUri === documentUri) continue; // Skip self\n\n // Create a mock SourceResource for symbolsFromResource\n const sourceDoc = this.getDocument(sourcedUri);\n if (!sourceDoc) continue;\n\n const topLevelDefinitions = this.getFlatDocumentSymbols(sourceDoc.uri).filter(s => s.isRootLevel() || s.isGlobal());\n sourcedSymbols.push(...topLevelDefinitions);\n\n for (const resource of createSourceResources(analyzer, sourceDoc)) {\n // If the resource is a sourced file, we can get its symbols\n if (resource.to && resource.from && resource.node) {\n const symbols = symbolsFromResource(this, resource, new Set(sourcedSymbols.map(s => s.name)))\n .filter(s => s.isRootLevel() || s.isGlobal());\n for (const symbol of symbols) {\n if (!uniqueNames.has(symbol.name)) {\n uniqueNames.add(symbol.name);\n sourcedSymbols.push(symbol);\n }\n }\n }\n }\n }\n\n return sourcedSymbols;\n }\n\n /**\n * Collects all reachable symbols for a document:\n * - local defined symbols inside the document itself\n * - all sourced symbols from reachable source files\n *\n * @param documentUri - the uri of the document to collect symbols for\n * @returns {FishSymbol[]} - array of all reachable symbols\n */\n public allReachableSymbols(documentUri: string): FishSymbol[] {\n const seenSymbols = this.getFlatDocumentSymbols(documentUri);\n analyzer.collectAllSources(documentUri).forEach((s) => {\n const cached = analyzer.analyzeUri(s);\n cached?.flatSymbols\n .filter(s => s.isRootLevel() || s.isGlobal())\n .filter(s => s.name !== 'argv')\n .forEach(sym => {\n seenSymbols.push(sym);\n });\n });\n return seenSymbols;\n }\n\n /**\n * Returns an object to be deconstructed, for the onComplete function in the server.\n * This function is necessary because the normal onComplete parse of the LspDocument\n * will commonly throw errors (user is incomplete typing a command, etc.). To avoid\n * inaccurate parses for the entire document, we instead parse just the current line\n * that the user is on, and send it to the shell script to complete.\n *\n * @Note: the position should not edited (pass in the direct position from the CompletionParams)\n *\n * @returns\n * line - the string output of the line the cursor is on\n * lineRootNode - the rootNode for the line that the cursor is on\n * lineCurrentNode - the last node in the line\n */\n public parseCurrentLine(\n document: LspDocument,\n position: Position,\n ): {\n line: string;\n word: string;\n lineRootNode: SyntaxNode;\n lineLastNode: SyntaxNode;\n } {\n const line = document\n .getLineBeforeCursor(position)\n .replace(/^(.*)\\n$/, '$1') || '';\n const word =\n this.wordAtPoint(\n document.uri,\n position.line,\n Math.max(position.character - 1, 0),\n ) || '';\n const lineRootNode = this.parser.parse(line).rootNode;\n const lineLastNode = lineRootNode.descendantForPosition({\n row: 0,\n column: line.length - 1,\n });\n return { line, word, lineRootNode, lineLastNode };\n }\n public wordAtPoint(\n uri: string,\n line: number,\n column: number,\n ): string | null {\n const node = this.nodeAtPoint(uri, line, column);\n\n if (!node || node.childCount > 0 || node.text.trim() === '') {\n return null;\n }\n\n // check if the current word is a node that contains a `=` sign, therefore\n // we don't want to return the whole word, but only the part before the `=`\n if (\n isAliasDefinitionName(node) ||\n isExportVariableDefinitionName(node)\n ) return node.text.split('=')[0]!.trim();\n\n return node.text.trim();\n }\n /**\n * Find the node at the given point.\n */\n public nodeAtPoint(\n uri: string,\n line: number,\n column: number,\n ): Parser.SyntaxNode | null {\n const tree = this.cache.getParsedTree(uri);\n if (!tree?.rootNode) {\n // Check for lacking rootNode (due to failed parse?)\n return null;\n }\n return tree.rootNode.descendantForPosition({ row: line, column });\n }\n\n /**\n * Find the name of the command at the given point.\n */\n public commandNameAtPoint(\n uri: string,\n line: number,\n column: number,\n ): string | null {\n let node = this.nodeAtPoint(uri, line, column);\n\n while (node && !isCommand(node)) {\n node = node.parent;\n }\n\n if (!node) return null;\n\n const firstChild = node.firstNamedChild;\n if (!firstChild || !isCommandName(firstChild)) return null;\n\n return firstChild.text.trim();\n }\n\n public commandAtPoint(\n uri: string,\n line: number,\n column: number,\n ): SyntaxNode | null {\n const node = this.nodeAtPoint(uri, line, column) ?? undefined;\n if (node && isCommand(node)) return node;\n const parentCommand = findParentCommand(node);\n return parentCommand;\n }\n\n /**\n * Get the text at the given location, using the range of the location to find the text\n * inside the range.\n * Super helpful for debugging Locations like references, renames, definitions, etc.\n */\n public getTextAtLocation(location: LSP.Location): string {\n const document = this.cache.getDocument(location.uri);\n if (!document) {\n return '';\n }\n const text = document.document.getText(location.range);\n return text;\n }\n\n public ensureCachedDocument(doc: LspDocument): AnalyzedDocument {\n if (this.cache.hasUri(doc.uri)) {\n const cachedDoc = this.cache.getDocument(doc.uri);\n if (cachedDoc?.document.version === doc.version && cachedDoc.document.getText() === doc.getText()) {\n return cachedDoc;\n }\n }\n return this.analyze(doc);\n }\n\n private getIterableUris(): DocumentUri[] {\n const currentWs = workspaceManager.current;\n if (currentWs) {\n return currentWs.uris.all;\n }\n return this.cache.uris();\n }\n}\n\n/**\n * @local\n * @class GlobalDefinitionCache\n *\n * @summary The cache for all of the analyzer's global FishSymbol's across all workspaces\n * analyzed.\n *\n * The enternal map uses the name of the symbol as the key, and the value is an array\n * of FishSymbol's that have the same name. This is because a symbol can be defined\n * multiple times in different scopes/workspaces, and we want to keep track of all of them.\n *\n * @see {@link analyzer.globalSymbols} the globally accessible location of this class\n */\nclass GlobalDefinitionCache {\n constructor(private _definitions: Map = new Map()) { }\n add(symbol: FishSymbol): void {\n const current = this._definitions.get(symbol.name) || [];\n if (!current.some(s => s.equals(symbol))) {\n current.push(symbol);\n }\n this._definitions.set(symbol.name, current);\n }\n removeSymbolsByUri(uri: string): void {\n for (const [name, symbols] of this._definitions.entries()) {\n const filtered = symbols.filter(symbol => symbol.uri !== uri);\n if (filtered.length === 0) {\n this._definitions.delete(name);\n } else {\n this._definitions.set(name, filtered);\n }\n }\n }\n find(name: string): FishSymbol[] {\n return this._definitions.get(name) || [];\n }\n findFirst(name: string): FishSymbol | undefined {\n const symbols = this.find(name);\n if (symbols.length === 0) {\n return undefined;\n }\n return symbols[0];\n }\n has(name: string): boolean {\n return this._definitions.has(name);\n }\n uniqueSymbols(): FishSymbol[] {\n const unique: FishSymbol[] = [];\n this.allNames.forEach(name => {\n const u = this.findFirst(name);\n if (u) {\n unique.push(u);\n }\n });\n return unique;\n }\n get allSymbols(): FishSymbol[] {\n const all: FishSymbol[] = [];\n for (const [_, symbols] of this._definitions.entries()) {\n all.push(...symbols);\n }\n return all;\n }\n get allNames(): string[] {\n return [...this._definitions.keys()];\n }\n get map(): Map {\n return this._definitions;\n }\n}\n\n/**\n * @local\n *\n * @summary The cache for all of the analyzed documents in the server.\n *\n * @see {@link analyzer.cache} the globally accessible location of this class\n * inside our analyzer instance\n *\n * The internal map uses the uri of the document as the key, and the value is\n * the AnalyzedDocument object that contains:\n * - LspDocument\n * - FishSymbols (the definitions in the Document)\n * - tree (from tree-sitter)\n * - `source` command arguments, SyntaxNode[]\n * - commands used in the document (array of strings)\n */\nclass AnalyzedDocumentCache {\n constructor(private _documents: Map = new Map()) { }\n uris(): string[] {\n return [...this._documents.keys()];\n }\n setDocument(uri: URI, analyzedDocument: AnalyzedDocument): void {\n this._documents.set(uri, analyzedDocument);\n }\n getDocument(uri: URI): AnalyzedDocument | undefined {\n if (!this._documents.has(uri)) {\n return undefined;\n }\n return this._documents.get(uri);\n }\n hasUri(uri: URI): boolean {\n return this._documents.has(uri);\n }\n updateUri(oldUri: URI, newUri: URI): void {\n const oldValue = this.getDocument(oldUri);\n if (oldValue) {\n this._documents.delete(oldUri);\n this._documents.set(newUri, oldValue);\n }\n }\n getDocumentSymbols(uri: URI): FishSymbol[] {\n const doc = this._documents.get(uri);\n if (doc) {\n doc.ensureParsed();\n return doc.documentSymbols;\n }\n return [];\n }\n getFlatDocumentSymbols(uri: URI): FishSymbol[] {\n return this._documents.get(uri)?.flatSymbols || [];\n }\n getCommands(uri: URI): SyntaxNode[] {\n const doc = this._documents.get(uri);\n if (doc) {\n doc.ensureParsed();\n return doc.commandNodes;\n }\n return [];\n }\n getRootNode(uri: URI): Parser.SyntaxNode | undefined {\n return this.getParsedTree(uri)?.rootNode;\n }\n getParsedTree(uri: URI): Parser.Tree | undefined {\n const doc = this._documents.get(uri);\n if (doc) {\n doc.ensureParsed();\n return doc.tree;\n }\n return undefined;\n }\n getSymbolTree(uri: URI): FishSymbol[] {\n const analyzedDoc = this._documents.get(uri);\n if (!analyzedDoc) {\n return [];\n }\n analyzedDoc.ensureParsed();\n return analyzedDoc.documentSymbols;\n }\n getSources(uri: URI): Set {\n const analyzedDoc = this._documents.get(uri);\n if (!analyzedDoc) {\n return new Set();\n }\n analyzedDoc.ensureParsed();\n const result: Set = new Set();\n\n // Get the base directory for resolving relative paths\n const fromPath = uriToPath(uri);\n const baseDir = dirname(fromPath);\n\n const sourceNodes = analyzedDoc.sourceNodes.map((node: any) => getExpandedSourcedFilenameNode(node, baseDir)).filter((s: any) => !!s) as string[];\n for (const source of sourceNodes) {\n const sourceUri = pathToUri(source);\n result.add(sourceUri);\n }\n return result;\n }\n getSourceNodes(uri: URI): SyntaxNode[] {\n const analyzedDoc = this._documents.get(uri);\n if (!analyzedDoc) {\n return [];\n }\n analyzedDoc.ensureParsed();\n return analyzedDoc.sourceNodes;\n }\n clear(uri: URI) {\n this._documents.delete(uri);\n }\n}\n\nexport function findCommandLocations(cmd: string) {\n const paths: { path: string; uri: DocumentUri; }[] = env.findAutoloadedFunctionPath(cmd).map(filePath => ({\n uri: pathToUri(filePath),\n path: filePath,\n }));\n if (paths.length === 0) {\n const potentialPaths = execCommandLocations(cmd).filter(p => {\n if (p.path.startsWith('embedded:')) return false;\n return SyncFileHelper.isFile(p.path);\n });\n paths.push(...potentialPaths);\n }\n return paths;\n}\n"
},
{
"path": "src/cli.ts",
"content": "import './utils/polyfills';\nimport { BuildCapabilityString, PathObj, PackageLspVersion, PackageVersion, accumulateStartupOptions, FishLspHelp, FishLspManPage, SourcesDict, SubcommandEnv, CommanderSubcommand, getBuildTypeString, PkgJson } from './utils/commander-cli-subcommands';\nimport { Command, Option } from 'commander';\nimport { buildFishLspAbbreviations, buildFishLspCompletions } from './utils/get-lsp-completions';\nimport { logger } from './logger';\nimport { configHandlers, config, updateHandlers, validHandlers, Config, handleEnvOutput } from './config';\nimport { ConnectionOptions, ConnectionType, createConnectionType, maxWidthForOutput, startServer, timeServerStartup } from './utils/startup';\nimport { performHealthCheck } from './utils/health-check';\nimport { setupProcessEnvExecFile } from './utils/process-env';\nimport { handleCLiDumpParseTree, handleCLiDumpSemanticTokens, handleCLiDumpSymbolTree } from './utils/cli-dump-tree';\nimport PackageJSON from '@package';\nimport chalk from 'chalk';\nimport vfs from './virtual-fs';\n\n/**\n * creates local 'commandBin' used for commander.js\n */\nconst createFishLspBin = (): Command => {\n const description = [\n 'Description:',\n FishLspHelp().description || 'An LSP for the fish shell language',\n ].join('\\n');\n const bin = new Command('fish-lsp')\n .description(description)\n .helpOption('-h, --help', 'show the relevant help info. Other `--help-*` flags are also available.')\n .version(PackageJSON.version, '-v, --version', 'output the version number')\n .enablePositionalOptions(true)\n .configureHelp({\n showGlobalOptions: false,\n sortSubcommands: true,\n commandUsage: (_) => FishLspHelp().usage,\n })\n .showSuggestionAfterError(true)\n .showHelpAfterError(true)\n .addHelpText('after', FishLspHelp().after);\n return bin;\n};\n\n// start adding options to the command\nexport const commandBin = createFishLspBin();\n\n// hidden global options\ncommandBin\n .addOption(new Option('--help-man', 'show special manpage output').hideHelp(true))\n .addOption(new Option('--help-all', 'show all help info').hideHelp(true))\n .addOption(new Option('--help-short', 'show mini help info').hideHelp(true))\n .action(opt => {\n if (opt.helpMan) {\n const { path: _path, content } = FishLspManPage();\n logger.logToStdout(content.join('\\n').trim());\n } else if (opt.helpAll) {\n const globalOpts = [new Option('-h, --help', 'show help'), ...commandBin.options];\n const allOpts = [\n ...globalOpts.map(o => o.flags),\n ...commandBin.commands.flatMap(c => c.options.map(o => o.flags)),\n ];\n\n const padAmount = Math.max(...allOpts.map(o => `${o}\\t`.length));\n const subCommands = commandBin.commands.map((cmd) => {\n return [\n ` ${cmd.name()} ${cmd.usage()}\\t${cmd.summary()}`,\n cmd.options.map(o => ` ${o.flags.padEnd(padAmount)}\\t${o.description}`).join('\\n'),\n ''].join('\\n');\n });\n const { beforeAll, after } = FishLspHelp();\n logger.logToStdout(['NAME:',\n 'fish-lsp - an lsp for the fish shell language',\n '',\n 'USAGE: ',\n beforeAll,\n '',\n 'DESCRIPTION:',\n ' ' + commandBin.description().split('\\n').slice(1).join('\\n').trim(),\n '',\n 'OPTIONS:',\n ' ' + globalOpts.map(o => ' ' + o.flags.padEnd(padAmount) + '\\t' + o.description).join('\\n').trim(),\n '',\n 'SUBCOMMANDS:',\n subCommands.join('\\n'),\n '',\n 'EXAMPLES:',\n after.split('\\n').slice(2).join('\\n'),\n ].join('\\n').trim());\n } else if (opt.helpShort) {\n logger.logToStdout([\n 'fish-lsp [OPTIONS]',\n 'fish-lsp [COMMAND] [OPTIONS]',\n '',\n commandBin.description(),\n ].join('\\n'));\n }\n return;\n });\n\n// START\ncommandBin.command('start')\n .summary('start the lsp')\n .description('start the language server for a connection to a client')\n .option('--dump', 'stop lsp & show the startup options being read')\n .option('--enable ', 'enable the startup option')\n .option('--disable ', 'disable the startup option')\n .option('--stdio', 'use stdin/stdout for communication (default)')\n .option('--node-ipc', 'use node IPC for communication')\n .option('--socket ', 'use TCP socket for communication')\n .option('--port ', 'use TCP socket for communication (alias for --socket)')\n .option('--memory-limit ', 'set memory usage limit in MB')\n .option('--max-files ', 'override the maximum number of files to analyze')\n .option('--web', 'start the server in web playground mode (fish-lsp.dev/playground)')\n .addHelpText('afterAll', [\n '',\n 'Strings for \\'--enable/--disable\\' switches:',\n `${validHandlers?.map((opt, index) => {\n return index < validHandlers.length - 1 && index > 0 && index % 5 === 0 ? `${opt},\\n` :\n index < validHandlers.length - 1 ? `${opt},` : opt;\n }).join(' ').split('\\n').map(line => `\\t${line.trim()}`).join('\\n')}`,\n '',\n 'Examples:',\n '\\t>_ fish-lsp start --disable hover # only disable the hover feature',\n '\\t>_ fish-lsp start --disable complete hover --dump',\n '\\t>_ fish-lsp start --enable --disable complete codeAction',\n '\\t>_ fish-lsp start --socket 3000 # start TCP server on port 3000 (useful for Docker)',\n ].join('\\n'))\n .allowUnknownOption(false)\n .action(async (opts: CommanderSubcommand.start.schemaType) => {\n await setupProcessEnvExecFile();\n // NOTE: `config` is a global object, already initialized. Here, we are updating its\n // values passed from the shell environment, and then possibly overriding them with\n // the command line args.\n\n // use the `config` object's shell environment values to update the handlers\n updateHandlers(config.fish_lsp_enabled_handlers, true);\n updateHandlers(config.fish_lsp_disabled_handlers, false);\n\n // Handle max files option\n if (opts.maxFiles && !isNaN(parseInt(opts.maxFiles))) {\n config.fish_lsp_max_background_files = parseInt(opts.maxFiles);\n }\n //\n // // Handle memory limit\n if (opts.memoryLimit && !isNaN(parseInt(opts.memoryLimit))) {\n const limitInMB = parseInt(opts.memoryLimit);\n process.env.NODE_OPTIONS = `--max-old-space-size=${limitInMB}`;\n }\n //\n // Determine connection type\n const portValue = opts.port || opts.socket;\n const connectionType: ConnectionType = createConnectionType({\n stdio: opts.stdio,\n nodeIpc: opts.nodeIpc,\n pipe: !!portValue,\n socket: false,\n });\n const connectionOptions: ConnectionOptions = {};\n if (portValue) {\n connectionOptions.port = parseInt(portValue, 10);\n }\n\n // override `configHandlers` with command line args\n const { enabled, disabled, dumpCmd } = accumulateStartupOptions(commandBin.args);\n updateHandlers(enabled, true);\n updateHandlers(disabled, false);\n Config.fixPopups(enabled, disabled);\n\n // Set web playground mode if requested\n if (opts.web) {\n Config.isWebServer = true;\n }\n\n // Dump the configHandlers, if requested from the command line. This stops the server.\n if (dumpCmd) {\n logger.logFallbackToStdout({ handlers: configHandlers });\n logger.logFallbackToStdout({ config: config });\n process.exit(0);\n }\n\n /* config needs to be used in `startServer()` below */\n startServer(connectionType, connectionOptions);\n });\n\n// INFO\ncommandBin.command('info')\n .summary('show info about the fish-lsp')\n .description('the info about the `fish-lsp` executable')\n .option('--bin', 'show the path of the fish-lsp executable', false)\n .option('--path', 'show the path of the entire fish-lsp repo', false)\n .option('--build-time', 'show the path of the entire fish-lsp repo', false)\n .option('--build-type', 'show the build type being used', false)\n .option('-v, --version', 'show the version of the fish-lsp package', false)\n .option('--lsp-version', 'show the lsp version', false)\n .option('--capabilities', 'show the lsp capabilities', false)\n .option('--man-file', 'show the man file path', false)\n .option('--show', 'show the man file output', false)\n .option('--logs-file', 'show the logs file path', false)\n .option('--log-file', 'show the log file path', false)\n .option('--verbose', 'show debugging server info (capabilities, paths, version, etc.)', false)\n .option('--extra', 'show debugging server info (capabilities, paths, version, etc.)', false)\n .option('--health-check', 'run diagnostics and report health status', false)\n .option('--check-health', 'run diagnostics and report health status', false)\n .option('--time-startup', 'time the startup of the fish-lsp executable', false)\n .option('--time-only', 'alias to show only the time taken for the server to index files', false)\n .option('--use-workspace ', 'use the specified workspace path for `fish-lsp info --time-startup`', undefined)\n .option('--no-warning', 'do not show warnings in the output for `fish-lsp info --time-startup`', true)\n .option('--show-files', 'show the files being indexed during `fish-lsp info --time-startup`', false)\n .option('--source-maps', 'show source map information and management options', false)\n .option('--all', 'show all source maps (use with --source-maps)', false)\n .option('--all-paths', 'show the paths to all the source maps (use with --source-maps)', false)\n .option('--install', 'download and install source maps (use with --source-maps)', false)\n .option('--remove', 'remove source maps (use with --source-maps)', false)\n .option('--check', 'check source map availability (use with --source-maps)', false)\n .option('--status', 'show the status of all the source-maps available to the server (use with --source-maps)', false)\n .option('--dump-parse-tree [FILE]', 'dump the tree-sitter parse tree of a file (reads from stdin if no file provided)', undefined)\n .option('--dump-semantic-tokens [FILE]', 'dump the semantic tokens of a file (reads from stdin if no file provided)', undefined)\n .option('--dump-symbol-tree [FILE]', 'dump the symbol tree of a file (reads from stdin if no file provided)', undefined)\n .option('--no-color', 'disable color output for --dump-parse-tree, --dump-semantic-tokens, and --dump-symbol-tree', false)\n .option('--no-icons', 'use plain text tags (f/v/e) instead of nerdfont icons for --dump-symbol-tree')\n .option('--virtual-fs', 'show the virtual filesystem structure (like tree command)', false)\n .allowUnknownOption(false)\n // .allowExcessArguments(false)\n .action(async (args: CommanderSubcommand.info.schemaType) => {\n await setupProcessEnvExecFile();\n const capabilities = BuildCapabilityString()\n .split('\\n')\n .map((line: string) => ` ${line}`).join('\\n');\n\n const hasTimingOpts = args.timeStartup || args.timeOnly;\n args.warning = !hasTimingOpts && args.warning === true ? !args.warning : args.warning;\n // Variable to determine if we saw specific info requests\n let shouldExit = false;\n let exitCode = 0;\n\n let argsCount = CommanderSubcommand.countArgsWithValues('info', args);\n if (args.warning && !hasTimingOpts) {\n argsCount = argsCount - 1;\n }\n\n const sourceMaps = CommanderSubcommand.info.sourcemaps();\n // immediately exit if the user requested a specific info\n CommanderSubcommand.info.handleBadArgs(args);\n\n if (args.dumpParseTree) {\n const status = await handleCLiDumpParseTree(args);\n process.exit(status);\n }\n\n if (args.dumpSemanticTokens) {\n const status = await handleCLiDumpSemanticTokens(args);\n process.exit(status);\n }\n\n if (args.dumpSymbolTree) {\n const status = await handleCLiDumpSymbolTree(args);\n process.exit(status);\n }\n\n // If the user requested specific info, we will try to show only the requested output.\n if (!args.verbose) {\n // handle the preferred args (`--time-startup`, `--health-check`, `--check-health`)\n if (args.timeStartup || args.timeOnly) {\n await timeServerStartup({\n workspacePath: args.useWorkspace,\n warning: args.warning,\n timeOnly: args.timeOnly,\n showFiles: args.showFiles,\n });\n process.exit(0);\n }\n if (args.healthCheck || args.checkHealth) {\n await performHealthCheck();\n process.exit(0);\n }\n\n // Handle sourcemaps (requires --source-maps or specific sourcemap options)\n if (args.sourceMaps) {\n exitCode = CommanderSubcommand.info.handleSourceMaps(args);\n shouldExit = true;\n }\n // normal info about the fish-lsp\n if (args.bin) {\n CommanderSubcommand.info.log(argsCount, 'Executable Path', PathObj.execFile);\n shouldExit = true;\n }\n if (args.path) {\n CommanderSubcommand.info.log(argsCount, 'Build Path', PathObj.path);\n shouldExit = true;\n }\n if (args.buildTime) {\n CommanderSubcommand.info.log(argsCount, 'Build Time', PkgJson.buildTime);\n shouldExit = true;\n }\n if (args.buildType) {\n CommanderSubcommand.info.log(argsCount, 'Build Type', getBuildTypeString());\n shouldExit = true;\n }\n if (args.capabilities) {\n CommanderSubcommand.info.log(argsCount, 'Capabilities', capabilities, true);\n shouldExit = true;\n }\n if (args.version) {\n CommanderSubcommand.info.log(argsCount, 'Build Version', PackageVersion);\n shouldExit = true;\n }\n if (args.lspVersion) {\n CommanderSubcommand.info.log(argsCount, 'LSP Version', PackageLspVersion, true);\n shouldExit = true;\n }\n // handle `[--man-file | --log-file] (--show)?`\n if (args.manFile || args.logFile || args.logsFile) {\n exitCode = CommanderSubcommand.info.handleFileArgs(args) || 0;\n shouldExit = true;\n }\n // handle `--virtual-fs`\n if (args.virtualFs) {\n argsCount = argsCount - 1;\n const tree = vfs.displayTree();\n CommanderSubcommand.info.log(argsCount, 'Virtual Filesystem', tree, true);\n shouldExit = true;\n }\n }\n if (!shouldExit || args.verbose) {\n CommanderSubcommand.info.log(argsCount, 'Executable Path', PathObj.execFile, true);\n CommanderSubcommand.info.log(argsCount, 'Build Location', PathObj.path, true);\n CommanderSubcommand.info.log(argsCount, 'Build Version', PackageVersion, true);\n CommanderSubcommand.info.log(argsCount, 'Build Time', PkgJson.buildTime, true);\n CommanderSubcommand.info.log(argsCount, 'Build Type', getBuildTypeString(), true);\n CommanderSubcommand.info.log(argsCount, 'Node Version', process.version, true);\n CommanderSubcommand.info.log(argsCount, 'LSP Version', PackageLspVersion, true);\n CommanderSubcommand.info.log(argsCount, 'Binary File', PathObj.bin, true);\n CommanderSubcommand.info.log(argsCount, 'Man File', PathObj.manFile, true);\n CommanderSubcommand.info.log(argsCount, 'Log File', config.fish_lsp_log_file, true);\n CommanderSubcommand.info.log(argsCount, 'Sourcemaps', sourceMaps, true);\n if (args.extra || args.capabilities || args.verbose) {\n logger.logToStdout('_'.repeat(maxWidthForOutput()));\n CommanderSubcommand.info.log(argsCount, 'Capabilities', capabilities, false);\n }\n }\n process.exit(exitCode);\n });\n\n// URL\ncommandBin.command('url')\n .summary('show helpful url(s) related to the fish-lsp')\n .description('show the related url to the fish-lsp')\n .option('--repo, --git', 'show the github repo')\n .option('--npm', 'show the npm package url')\n .option('--homepage', 'show the homepage')\n .option('--contributions', 'show the contributions url')\n .option('--wiki', 'show the github wiki')\n .option('--issues, --report', 'show the issues page')\n .option('--discussions', 'show the discussions page')\n .option('--clients-repo', 'show the clients configuration repo')\n .option('--sources-list', 'show a list of helpful sources')\n .option('--source-map', 'show source map download url for current version')\n .allowUnknownOption(false)\n .allowExcessArguments(false)\n .action(async (args: CommanderSubcommand.url.schemaType) => {\n const amount = Object.keys(args).length;\n if (amount === 0) {\n logger.logToStdout('https://fish-lsp.dev');\n process.exit(0);\n }\n\n Object.keys(args).forEach(key => logger.logToStdout(SourcesDict[key]?.toString() || ''));\n process.exit(0);\n });\n\n// COMPLETE\ncommandBin.command('complete')\n .summary('generate fish shell completions')\n .description('the completions for the `fish-lsp` executable')\n .option('--names', 'show the feature names of the completions')\n .option('--names-with-summary', 'show names with their summary for a completions script')\n .option('--toggles', 'show the feature names of the completions')\n .option('--fish', 'show fish script')\n .option('--features', 'show features')\n .option('--env-variables', 'show env variables')\n .option('--env-variable-names', 'show env variable names')\n .option('--abbreviations', 'show abbreviations')\n .description('copy completions output to fish-lsp completions file')\n .allowUnknownOption(false)\n .action(async (args: CommanderSubcommand.complete.schemaType) => {\n await setupProcessEnvExecFile();\n if (args.names) {\n commandBin.commands.forEach(cmd => logger.logToStdout(cmd.name()));\n process.exit(0);\n } else if (args.namesWithSummary) {\n commandBin.commands.forEach(cmd => logger.logToStdout(cmd.name() + '\\t' + cmd.summary()));\n process.exit(0);\n } else if (args.fish) {\n logger.logToStdout(buildFishLspCompletions(commandBin));\n process.exit(0);\n } else if (args.features || args.toggles) {\n Object.keys(configHandlers).forEach((name) => logger.logToStdout(name.toString()));\n process.exit(0);\n } else if (args.envVariables) {\n Object.entries(Config.envDocs).forEach(([key, value]) => {\n logger.logToStdout(`${key}\\\\t'${value}'`);\n });\n process.exit(0);\n } else if (args.envVariableNames) {\n Object.keys(Config.envDocs).forEach((name) => logger.logToStdout(name.toString()));\n process.exit(0);\n } else if (args.abbreviations) {\n logger.logToStdout(buildFishLspAbbreviations());\n if (Object.values(args).filter(v => v === true).length === 1) process.exit(0);\n }\n\n logger.logToStdout(buildFishLspCompletions(commandBin));\n process.exit(0);\n });\n\n// ENV\ncommandBin.command('env')\n .summary('generate environment variables for lsp configuration')\n .description('generate fish-lsp env variables')\n .option('-c, --create', 'build initial fish-lsp env variables')\n .option('-s, --show', 'show the current fish-lsp env variables')\n .option('--show-default', 'show the default fish-lsp env variables')\n .option('--only ', 'only show specified variables (comma-separated)')\n .option('--no-comments', 'skip comments in output')\n .option('--no-global', 'use local env variables')\n .option('--no-local', 'do not use local scope for variables')\n .option('--no-export', 'don\\'t export the variables')\n .option('--confd', 'output for piping to conf.d')\n .option('--names', 'show only the variable names')\n .option('--joined', 'print the names in a single line')\n .option('--json', 'output in JSON format')\n .allowUnknownOption(false)\n .allowExcessArguments(false)\n .action(async (args: SubcommandEnv.ArgsType) => {\n await setupProcessEnvExecFile();\n\n const outputType = SubcommandEnv.getOutputType(args);\n const opts = SubcommandEnv.toEnvOutputOptions(args);\n if (args.names) {\n let result = '';\n Object.keys(Config.envDocs).forEach((name) => {\n if (args?.only && args.only.length > 0 && !args.only.includes(name)) {\n logger.logToStderr(chalk.red(`\\n[ERROR] Unknown variable name '${name} ' in --only option.`));\n logger.logToStderr(`Valid variable names are:\\n${Object.keys(Config.envDocs).join(', ')}`);\n process.exit(1);\n }\n result += args.joined ? `${name} ` : `${name}\\n`;\n });\n logger.logToStdout(result.trim());\n process.exit(0);\n }\n handleEnvOutput(outputType, logger.logToStdout, opts);\n process.exit(0);\n });\n\n// Parsing the command now happens in the `src / main.ts` file, since our bundler\nexport function execCLI() {\n if (process.argv.length <= 2) {\n logger.logToStderr(chalk.red('[ERROR] No COMMAND provided to `fish - lsp`, displaying `fish - lsp--help` output.\\n'));\n commandBin.outputHelp();\n logger.logToStdout('\\nFor more help, use `fish - lsp--help - all` to see all commands and options.');\n process.exit(1);\n }\n // commandBin.parse(process.argv);\n commandBin.parse();\n}\n"
},
{
"path": "src/code-actions/action-kinds.ts",
"content": "import { CodeActionKind } from 'vscode-languageserver';\n\n// Define our supported code action kinds\nexport const SupportedCodeActionKinds = {\n QuickFix: `${CodeActionKind.QuickFix}.fix`,\n Disable: `${CodeActionKind.QuickFix}.disable`,\n QuickFixAll: `${CodeActionKind.QuickFix}.fixAll`,\n QuickFixDelete: `${CodeActionKind.QuickFix}.delete`,\n RefactorRewrite: `${CodeActionKind.Refactor}.rewrite`,\n RefactorExtract: `${CodeActionKind.Refactor}.extract`,\n SourceRename: `${CodeActionKind.Source}.rename`,\n} as const;\n\nexport type SupportedCodeActionKinds = typeof SupportedCodeActionKinds[keyof typeof SupportedCodeActionKinds];\n\nexport const AllSupportedActions = Object.values(SupportedCodeActionKinds);\n"
},
{
"path": "src/code-actions/alias-wrapper.ts",
"content": "import * as os from 'os';\nimport { CodeAction, CreateFile, TextDocumentEdit, TextEdit, VersionedTextDocumentIdentifier, WorkspaceEdit } from 'vscode-languageserver';\nimport { SyntaxNode } from 'web-tree-sitter';\nimport { getRange } from '../utils/tree-sitter';\nimport { LspDocument } from '../document';\nimport { execAsyncF } from '../utils/exec';\nimport { join } from 'path';\nimport { SupportedCodeActionKinds } from './action-kinds';\nimport { pathToUri } from '../utils/translation';\n\n/**\n * Extracts the function name from an alias node\n * ---\n *\n * ```fish\n * # handles both cases\n * alias name='cmd'\n * alias name 'cmd'\n * ```\n *\n * ---\n * @param node The alias node\n * @returns The function name\n */\nfunction extractFunctionName(node: SyntaxNode): string {\n const children = node.children;\n if (children.length < 2) return '';\n\n const nameNode = children[1];\n if (!nameNode) return '';\n\n // Handle both formats: alias name='cmd' and alias name 'cmd'\n const name = nameNode.text.split('=')[0]?.toString() || '';\n return name.trim();\n}\n\n/**\n * Creates a quick-fix code action to convert an alias to a function inline\n * This action will replace the alias line with the function content.\n */\nexport async function createAliasInlineAction(\n doc: LspDocument,\n node: SyntaxNode,\n): Promise {\n const aliasCommand = node.text;\n const funcName = extractFunctionName(node);\n\n if (!funcName) {\n return undefined;\n }\n\n const stdout = await execAsyncF(`${aliasCommand} && functions ${funcName} | tail +2 | fish_indent`);\n const edit = TextEdit.replace(\n getRange(node),\n `\\n${stdout}\\n`,\n );\n\n return {\n title: `Convert alias '${funcName}' to inline function`,\n kind: SupportedCodeActionKinds.RefactorExtract,\n edit: {\n changes: {\n [doc.uri]: [edit],\n },\n },\n isPreferred: true,\n };\n}\n\nfunction createVersionedDocument(uri: string) {\n return VersionedTextDocumentIdentifier.create(uri, 0);\n}\n\nfunction createFunctionFileEdit(functionUri: string, content: string) {\n return TextDocumentEdit.create(\n createVersionedDocument(functionUri),\n [TextEdit.insert({ line: 0, character: 0 }, content)],\n );\n}\n\nfunction createRemoveAliasEdit(document: LspDocument, node: SyntaxNode) {\n return TextDocumentEdit.create(\n createVersionedDocument(document.uri),\n [TextEdit.del(getRange(node))],\n );\n}\n\n/**\n * Creates a quick-fix code action to convert an alias to a function file.\n */\nexport async function createAliasSaveActionNewFile(\n doc: LspDocument,\n node: SyntaxNode,\n): Promise {\n const aliasCommand = node.text;\n const funcName = extractFunctionName(node);\n\n // Get function content but remove first line (function declaration) and indent\n const functionContent = await execAsyncF(`${aliasCommand} && functions ${funcName} | tail +2 | fish_indent`);\n\n // Create path for new function file\n const functionPath = join(os.homedir(), '.config', 'fish', 'functions', `${funcName}.fish`);\n const functionUri = pathToUri(functionPath);\n\n // const createFileAction = OptionalVersionedTextDocumentIdentifier.create(functionUri, null)\n\n const createFileAction = CreateFile.create(functionUri, {\n ignoreIfExists: false,\n overwrite: true,\n });\n\n const workspaceEdit: WorkspaceEdit = {\n documentChanges: [\n createFileAction,\n createFunctionFileEdit(functionUri, functionContent),\n createRemoveAliasEdit(doc, node),\n ],\n };\n\n return {\n title: `Convert alias '${funcName}' to function in file: ~/.config/fish/functions/${funcName}.fish`,\n kind: SupportedCodeActionKinds.RefactorExtract,\n edit: workspaceEdit,\n isPreferred: false,\n };\n}\n\n/**\n * Extra exports for testing purposes\n */\nexport const AliasHelper = {\n extractFunctionName,\n createAliasInlineAction,\n createAliasSaveActionNewFile,\n} as const;\n"
},
{
"path": "src/code-actions/argparse-completions.ts",
"content": "import { SyntaxNode } from 'web-tree-sitter';\nimport { findParentFunction, isCommandWithName, isFunctionDefinition, isString } from '../utils/node-types';\nimport { getChildNodes, getRange } from '../utils/tree-sitter';\nimport { LspDocument } from '../document';\nimport { ChangeAnnotation, CodeAction, CodeActionKind, TextDocumentEdit, TextEdit, VersionedTextDocumentIdentifier, WorkspaceEdit } from 'vscode-languageserver';\nimport { extractFunctionWithArgparseToCompletionsFile } from './refactors';\nimport { uriToReadablePath } from '../utils/translation';\nimport { logger } from '../logger';\nimport { findArgparseDefinitionNames } from '../parsing/argparse';\n\nexport type CompleteFlag = {\n shortOption?: string;\n longOption: string;\n};\n\n// export function parseArgparseFlag(text: string): CompleteFlag {\nfunction parseArgparseFlag(node: SyntaxNode): CompleteFlag {\n let text = node.text;\n if (isString(node)) text = text.slice(1, -1);\n\n // Remove any equals and following text\n const beforeEquals = text.split('=')[0] as string;\n\n // Check if it has a short/long split with '/'\n if (beforeEquals.includes('/')) {\n const [short, long] = beforeEquals.split('/') as [string, string];\n return {\n shortOption: short,\n longOption: long === '' ? '' : long,\n };\n }\n\n // No short option, just return as long option\n return {\n longOption: beforeEquals,\n };\n}\n\nexport function findFlagsToComplete(node: SyntaxNode): CompleteFlag[] {\n if (!isCommandWithName(node, 'argparse')) return [];\n const flags: CompleteFlag[] = [];\n for (const n of findArgparseDefinitionNames(node)) {\n flags.push(parseArgparseFlag(n));\n }\n return flags;\n}\n\nexport function buildCompleteString(commandName: string, flags: CompleteFlag[]): string {\n return flags.map(flag => {\n let text = `complete -c ${commandName}`;\n if (flag.shortOption) {\n text += ` -s ${flag.shortOption}`;\n }\n if (flag.longOption) {\n text += ` -l ${flag.longOption}`;\n }\n return text;\n }).join('\\n');\n}\n\n/**\n * Helper function to build `argparse` completions for the current function in a\n * `conf.d/file.fish` file.\n * ___\n * Some example input can be seen below:\n * ___\n * ```fish\n * # ~/.config/fish/conf.d/file.fish\n * function some_function\n * argparse h/help o/option= v/verbose -- $argv\n * or return\n *\n * echo 'do some stuff'\n * end\n * ```\n * ___\n * @param argparseNode The `argparse` node\n * @param functionNode The `function_definition` node\n * @param functionNameNode The `functionNode.firstNamedChild` node containing the name of the function\n * @returns A `CodeAction` object to create the completions file\n */\nfunction buildConfdCompletions(\n argparseNode: SyntaxNode,\n functionNode: SyntaxNode,\n functionNameNode: SyntaxNode,\n doc: LspDocument,\n): CodeAction | undefined {\n logger.log(buildConfdCompletions.name, 'params', {\n argparseNode: argparseNode.text,\n functionNode: functionNode.text,\n functionNameNode: functionNameNode.text,\n doc: doc.uri,\n });\n // get the path to the completions file. Should be in the conf.d directory\n const completionPath = doc.getRelativeFilenameToWorkspace();\n // get the flags and the function name\n const flags = findFlagsToComplete(argparseNode);\n if (!isFunctionDefinition(functionNode)) {\n return undefined;\n }\n const functionName = functionNode.firstNamedChild!.text;\n // build the `complete -c command -s -l` string\n const completionText = buildCompleteString(functionName, flags);\n // Get the text to insert\n const selectedText = `\\n# auto generated by fish-lsp\\n${completionText}\\n`;\n const shortPath = doc.isFunced() || doc.isCommandlineBuffer()\n ? doc.getRelativeFilenameToWorkspace()\n : uriToReadablePath(completionPath);\n\n // Create a change annotation\n const changeAnnotation: ChangeAnnotation = {\n label: `Create completions for '${functionName}' in file: ${shortPath}`,\n description: `Create completions for '${functionName}' to file: ${shortPath}`,\n };\n // build the workspace edit\n const workspaceEdit: WorkspaceEdit = {\n documentChanges: [\n TextDocumentEdit.create(\n VersionedTextDocumentIdentifier.create(doc.uri, 0),\n [TextEdit.insert(getRange(functionNode).end, selectedText)]),\n ],\n changeAnnotations: { [changeAnnotation.label]: changeAnnotation },\n };\n logger.log(buildConfdCompletions.name, 'return', {\n textEdits: workspaceEdit.documentChanges,\n });\n return {\n title: `Create completions for '${functionName}' function`,\n kind: CodeActionKind.QuickFix,\n edit: workspaceEdit,\n };\n}\n\nfunction getNodesForArgparse(selectedNode: SyntaxNode) {\n const node = selectedNode;\n if (isCommandWithName(node, 'argparse')) {\n const functionNode = findParentFunction(node);\n return {\n argparseNode: node,\n functionNode: functionNode,\n functionNameNode: functionNode?.firstNamedChild,\n };\n }\n if (node.type === 'word' && node.parent && isCommandWithName(node.parent, 'argparse')) {\n const functionNode = findParentFunction(node.parent);\n return {\n argparseNode: node.parent,\n functionNode: functionNode,\n functionNameNode: functionNode?.firstNamedChild,\n };\n }\n if (node.type === 'function_definition') {\n return {\n argparseNode: getChildNodes(node).find(n => isCommandWithName(n, 'argparse')),\n functionNode: node,\n functionNameNode: node.firstNamedChild,\n };\n }\n return {\n argparseNode: undefined,\n functionNode: undefined,\n functionNameNode: undefined,\n };\n}\n\nexport function createArgparseCompletionsCodeAction(\n node: SyntaxNode,\n doc: LspDocument,\n): CodeAction | undefined {\n const autoloadType = doc.getAutoloadType();\n const { argparseNode, functionNode, functionNameNode } = getNodesForArgparse(node);\n\n if (!argparseNode || !functionNode || !functionNameNode) return undefined;\n\n if (autoloadType === 'functions') {\n return extractFunctionWithArgparseToCompletionsFile(doc, getRange(functionNode), functionNode);\n }\n if (autoloadType === 'conf.d') {\n const action = buildConfdCompletions(argparseNode, functionNode, functionNameNode, doc);\n logger.log('buildConfdCompletions returned', { title: action?.title });\n return action;\n }\n return undefined;\n}\n"
},
{
"path": "src/code-actions/code-action-handler.ts",
"content": "import { CodeAction, CodeActionParams, Diagnostic, Range } from 'vscode-languageserver';\nimport { getDisableDiagnosticActions } from './disable-actions';\nimport { createFixAllAction, getQuickFixes } from './quick-fixes';\nimport { logger } from '../logger';\nimport { documents, LspDocument } from '../document';\nimport { analyzer, Analyzer } from '../analyze';\nimport { findFirstParent, getNodeAtRange } from '../utils/tree-sitter';\nimport { convertIfToCombiners, extractCommandToFunction, extractFunctionToFile, extractFunctionWithArgparseToCompletionsFile, extractToVariable, replaceAbsolutePathWithVariable, simplifySetAppendPrepend } from './refactors';\nimport { createArgparseCompletionsCodeAction } from './argparse-completions';\nimport { isCommandName, isCommandWithName, isProgram, isAliasDefinitionName, isCommand } from '../utils/node-types';\nimport { createAliasInlineAction, createAliasSaveActionNewFile } from './alias-wrapper';\nimport { SyntaxNode } from 'web-tree-sitter';\nimport { handleRedirectActions } from './redirect-actions';\n\n/**\n * Sort code actions by kind to group similar actions together\n */\nfunction sortCodeActionsByKind(actions: CodeAction[]): CodeAction[] {\n const kindOrder = {\n 'quickfix.disable': 0, // Disable comments first\n 'quickfix.fix': 1, // Then quick fixes\n 'quickfix.fixAll': 2, // Then fix all\n 'refactor.extract': 3, // Then extractions\n 'refactor.rewrite': 4, // Then rewrites (redirects, prefixes, etc.)\n 'source.rename': 5, // Then renames\n };\n\n return actions.sort((a, b) => {\n const orderA = a.kind ? kindOrder[a.kind as keyof typeof kindOrder] ?? 999 : 999;\n const orderB = b.kind ? kindOrder[b.kind as keyof typeof kindOrder] ?? 999 : 999;\n return orderA - orderB;\n });\n}\n\n/**\n * Check if a range represents a selection (non-zero width)\n */\nfunction isSelection(range: Range): boolean {\n return range.start.line !== range.end.line ||\n range.start.character !== range.end.character;\n}\n\nexport function getParentCommandNodeForCodeAction(node: SyntaxNode | null): SyntaxNode | null {\n if (!node) return null;\n return findFirstParent(node, isCommand);\n}\n\nexport function createCodeActionHandler() {\n /**\n * small helper for now, used to add code actions that are not `preferred`\n * quickfixes to the list of results, when a quickfix is requested.\n */\n async function getSelectionCodeActions(document: LspDocument, range: Range) {\n const rootNode = analyzer.getRootNode(document.uri);\n if (!rootNode) return [];\n\n const selectedNode = getNodeAtRange(rootNode, range);\n if (!selectedNode) return [];\n\n logger.log('getSelectionCodeActions', {\n selectedNodeType: selectedNode.type,\n selectedNodeText: selectedNode.text.substring(0, 50),\n isProgram: isProgram(selectedNode),\n isCommandWithNameArgparse: isCommandWithName(selectedNode, 'argparse'),\n parentType: selectedNode.parent?.type,\n parentIsArgparse: selectedNode.parent ? isCommandWithName(selectedNode.parent, 'argparse') : false,\n });\n\n const commands: SyntaxNode[] = [];\n\n const results: CodeAction[] = [];\n if (isProgram(selectedNode)) {\n const MAX_REDIRECT_COMMANDS = 2;\n const cursorPosition = range.start;\n const commandsForRedirect: SyntaxNode[] = [];\n\n // First pass: collect all command nodes and handle argparse\n analyzer.getNodes(document.uri).forEach(n => {\n if (isCommandWithName(n, 'argparse')) {\n const argparseAction = createArgparseCompletionsCodeAction(n, document);\n if (argparseAction) results.push(argparseAction);\n }\n if (isCommandName(n) && !commands.some(c => n.id === c.id)) {\n commands.push(n);\n commandsForRedirect.push(n);\n }\n // if (isIfStatement(n)) {\n // const convertIfAction = convertIfToCombiners(document, n, false);\n // if (convertIfAction) results.push(convertIfAction);\n // }\n });\n\n // Sort commands by distance to cursor and take the 2 closest\n const closestCommands = commandsForRedirect\n .sort((a, b) => {\n const distA = Math.abs(a.startPosition.row - cursorPosition.line);\n const distB = Math.abs(b.startPosition.row - cursorPosition.line);\n return distA - distB;\n })\n .slice(0, MAX_REDIRECT_COMMANDS);\n\n // Add redirect actions only for the closest commands\n closestCommands.forEach(n => {\n const redirectActions = handleRedirectActions(document, n.parent!);\n if (redirectActions) results.push(...redirectActions);\n });\n }\n\n // Note: Alias refactoring is handled in processRefactors to avoid duplication\n // Note: extractCommandToFunction is handled in processRefactors to avoid duplication\n if (isCommandWithName(selectedNode, 'argparse')) {\n const argparseAction = createArgparseCompletionsCodeAction(selectedNode, document);\n if (argparseAction) results.push(argparseAction);\n } else if (selectedNode.parent && isCommandWithName(selectedNode.parent, 'argparse')) {\n // Also handle when cursor is on a child of argparse command (e.g., on the word \"argparse\")\n const argparseAction = createArgparseCompletionsCodeAction(selectedNode.parent, document);\n if (argparseAction) results.push(argparseAction);\n }\n\n if (isCommandName(selectedNode) && !commands.some(c => selectedNode.id === c.id)) {\n commands.push(selectedNode);\n const redirectActions = handleRedirectActions(document, selectedNode.parent!);\n if (redirectActions) results.push(...redirectActions);\n }\n\n // if (isCommand(selectedNode) || hasParent(selectedNode, isCommand) && !commands.some(c => selectedNode.id === c.id)) {\n // commands.push(selectedNode);\n // const addSilenceAction = silenceCommandAction(document, selectedNode);\n // if (addSilenceAction) results.push(addSilenceAction);\n // }\n\n if (results.length === 0) {\n logger.log('No selection code actions for node', selectedNode.type, selectedNode.text);\n }\n\n return results;\n }\n\n /**\n * Helper to add quick fixes to the list that are mostly of the type `preferred`\n *\n * These quick fixes include things like `disable` actions, and general fixes to silence diagnostics\n */\n async function processQuickFixes(document: LspDocument, diagnostics: Diagnostic[], analyzer: Analyzer) {\n const results: CodeAction[] = [];\n for (const diagnostic of diagnostics) {\n logger.log('Processing diagnostic', diagnostic.code, diagnostic.message);\n const quickFixs = await getQuickFixes(document, diagnostic, analyzer);\n for (const fix of quickFixs) {\n logger.log('QuickFix', fix?.title);\n }\n if (quickFixs) results.push(...quickFixs);\n }\n return results;\n }\n\n /**\n * Process refactors for the given document and range\n */\n async function processRefactors(document: LspDocument, range: Range) {\n const results: CodeAction[] = [];\n\n const rootNode = analyzer.getRootNode(document.uri);\n if (!rootNode) return results;\n\n // Get node at the selected range\n const selectedNode = getNodeAtRange(rootNode, range);\n if (!selectedNode) return results;\n\n // try refactoring aliases first\n let aliasCommand = selectedNode;\n\n // Check if cursor is on the 'alias' keyword\n if (selectedNode.text === 'alias') {\n aliasCommand = selectedNode.parent!;\n\n // Check if cursor is on the alias definition name (e.g., \"foo\" in \"alias foo=bar\")\n } else if (isAliasDefinitionName(selectedNode)) {\n aliasCommand = selectedNode.parent?.type === 'concatenation'\n ? selectedNode.parent.parent!\n : selectedNode.parent!;\n }\n\n if (aliasCommand && isCommandWithName(aliasCommand, 'alias')) {\n logger.log('isCommandWithName(alias)', aliasCommand.text);\n const aliasInlineFunction = await createAliasInlineAction(document, aliasCommand);\n const aliasNewFile = await createAliasSaveActionNewFile(document, aliasCommand);\n if (aliasInlineFunction) results.push(aliasInlineFunction);\n if (aliasNewFile) results.push(aliasNewFile);\n return results;\n }\n\n // Try each refactoring action\n // const extractFunction = extractToFunction(document, range);\n // if (extractFunction) results.push(extractFunction);\n // const selectedRange = isSelection(range) ? range : undefined;\n\n // Pass range and selection info to extractCommandToFunction\n if (!isSelection(range)) {\n const extractCommandFunction = extractCommandToFunction(\n document,\n isSelection(range) ? range : undefined,\n selectedNode,\n );\n if (extractCommandFunction) results.push(extractCommandFunction);\n\n const extractVar = extractToVariable(document, range, selectedNode);\n if (extractVar) results.push(extractVar);\n }\n\n const extractFuncToFile = extractFunctionToFile(document, range, selectedNode);\n if (extractFuncToFile) results.push(extractFuncToFile);\n\n const extractCompletionToFile = extractFunctionWithArgparseToCompletionsFile(document, range, selectedNode);\n if (extractCompletionToFile) results.push(extractCompletionToFile);\n\n const convertIf = convertIfToCombiners(document, selectedNode);\n if (convertIf) results.push(convertIf);\n\n const replacePathWithVarActions = replaceAbsolutePathWithVariable(document, range);\n results.push(...replacePathWithVarActions);\n\n const simplifySetActions = simplifySetAppendPrepend(document, selectedNode);\n results.push(...simplifySetActions);\n\n return results;\n }\n\n return async function handleCodeAction(params: CodeActionParams): Promise {\n logger.debug('onCodeAction', {\n params: {\n context: {\n only: params.context.only,\n diagnostics: params.context.diagnostics.map(d => `${d.code}:${d.range.start.line}`),\n triggerKind: params.context.triggerKind?.toString(),\n },\n uri: params.textDocument.uri,\n range: params.range,\n isSelection: isSelection(params.range),\n },\n });\n\n const document = documents.get(params.textDocument.uri);\n if (!document) return [];\n\n const results: CodeAction[] = [];\n\n // only process diagnostics from the fish-lsp source\n const diagnostics = params.context.diagnostics\n .filter(d => !!d?.severity)\n .filter(d => d.source === 'fish-lsp');\n\n // Check what kinds of actions are requested\n const onlyRefactoring = params.context.only?.some(kind => kind.startsWith('refactor'));\n const onlyQuickFix = params.context.only?.some(kind => kind.startsWith('quickfix'));\n\n logger.log('Requested actions', { onlyRefactoring, onlyQuickFix });\n logger.log('Diagnostics', diagnostics.map(d => ({ code: d.code, message: d.message })));\n\n // Add disable actions\n if (diagnostics.length > 0 && !onlyRefactoring) {\n const disableActions = getDisableDiagnosticActions(document, diagnostics);\n logger.log('Disable actions', disableActions.map(a => a.title));\n for (const action of disableActions) {\n if (results.every(existing => existing.title !== action.title)) {\n results.push(action);\n }\n }\n }\n // Add quick fixes if requested\n if (onlyQuickFix) {\n logger.log('Processing onlyQuickFixes');\n results.push(...await processQuickFixes(document, diagnostics, analyzer));\n results.push(...await getSelectionCodeActions(document, params.range));\n const allAction = createFixAllAction(document, results);\n if (allAction) results.push(allAction);\n logger.log('CodeAction results', results.map(r => r.title));\n return sortCodeActionsByKind(results);\n }\n\n // add the refactors\n if (onlyRefactoring) {\n logger.log('Processing onlyRefactors');\n results.push(...await processRefactors(document, params.range));\n logger.log('CodeAction results', results.map(r => r.title));\n return sortCodeActionsByKind(results);\n }\n\n logger.log('Processing all actions');\n results.push(...await processQuickFixes(document, diagnostics, analyzer));\n results.push(...await getSelectionCodeActions(document, params.range));\n results.push(...await processRefactors(document, params.range));\n const allAction = createFixAllAction(document, results);\n if (allAction) {\n logger.log({\n name: 'allAction',\n title: allAction.title,\n kind: allAction.kind,\n diagnostics: diagnostics?.map(d => d.message),\n edit: allAction.edit,\n });\n results.push(allAction);\n }\n logger.log('CodeAction results', results.map(r => r.title));\n return sortCodeActionsByKind(results);\n };\n}\n\nexport function equalDiagnostics(d1: Diagnostic, d2: Diagnostic) {\n return d1.code === d2.code &&\n d1.message === d2.message &&\n d1.range.start.line === d2.range.start.line &&\n d1.range.start.character === d2.range.start.character &&\n d1.range.end.line === d2.range.end.line &&\n d1.range.end.character === d2.range.end.character &&\n d1.data.node?.text === d2.data.node?.text;\n}\n\nexport function createOnCodeActionResolveHandler() {\n return async function codeActionResolover(codeAction: CodeAction) {\n return codeAction;\n };\n}\n\nexport function codeActionHandlers() {\n return {\n onCodeActionCallback: createCodeActionHandler(),\n onCodeActionResolveCallback: createOnCodeActionResolveHandler(),\n };\n}\n"
},
{
"path": "src/code-actions/combiner.ts",
"content": "import { SyntaxNode } from 'web-tree-sitter';\nimport { getNamedChildNodes } from '../utils/tree-sitter';\nimport { isConditional } from '../utils/node-types';\n\n/**\n * Code Action utility function to convert an if_statement node into a sequence of combiner commands.\n * ___\n * ```fish\n * if test -f file\n * echo \"file exists\"\n * else\n * echo \"file does not exist\"\n * end\n * ```\n * ___\n * Would Become:\n * ___\n * ```fish\n * test -f file\n * and echo \"file exists\"\n *\n * or echo \"file does not exist\"\n * ```\n * ___\n * @param node the if_statement node to convert into a sequence of combiner commands.\n * @returns a string representation of the if_statement node, with the if/else-if/else blocks combined.\n */\nexport function convertIfToCombinersString(node: SyntaxNode) {\n const combiner = new StatementCombiner();\n const queue: SyntaxNode[] = getNamedChildNodes(node);\n while (queue.length > 0) {\n const n = queue.shift();\n if (!n) break;\n switch (true) {\n case isConditional(n):\n combiner.newBlock(n.type as BlockKeywordType);\n break;\n case n.type === 'negated_statement':\n case n.type === 'conditional_execution':\n combiner.appendCommand(n);\n skipChildren(n, queue);\n break;\n case n.type === 'comment':\n case n.type === 'command':\n combiner.appendCommand(n);\n break;\n }\n }\n return combiner.build();\n}\n\n/**\n * Utility function to skip children nodes that are not part of the current node.\n */\nfunction skipChildren(node: SyntaxNode, queue: SyntaxNode[]) {\n while (queue.length > 0) {\n const peek = queue.at(0);\n if (!peek) break;\n if (peek.endIndex > node.endIndex || peek.startIndex < node.startIndex) break;\n queue.shift();\n }\n}\n\n/** Types of conditional blocks, defined in tree-sitter-fish grammar **/\ntype BlockKeywordType = 'if_statement' | 'else_if_clause' | 'else_clause';\n\n/**\n * Data structure to represent a conditional block in the fish language.\n * A conditional block is a series of commands that are executed based on a condition.\n * ___\n * ```fish\n * if test -f file\n * echo \"file exists\"\n * end\n * ```\n * ___\n * Would become:\n * ___\n * ```typescript\n * {\n * keyword: 'if_statement',\n * body: [\n * { type: 'command', text: 'test -f file' },\n * { type: 'command', text: 'echo \"file exists\"' }\n * ],\n * }\n * ```\n */\ninterface ConditionalBlock {\n /** the type of conditional block */\n keyword: BlockKeywordType;\n /** the commands that make up the conditional block */\n body: SyntaxNode[];\n}\n\nnamespace ConditionalBlock {\n /**\n * Creates a new conditional block. Typically the body will be empty, since\n * a `if`/`else-if`/`else` block will always come before the body it contains.\n * @param keyword The type of conditional block\n * @param body The commands that make up the conditional block\n * @returns The new conditional block\n */\n export function create(keyword: BlockKeywordType, body: SyntaxNode[] = []) {\n return { keyword, body };\n }\n}\n\n/**\n * Helper class to combine statements together, based on their conditional blocks.\n *\n * This class converts if/else-if/else blocks into a single string, with the\n * appropriate combiners (and/or) between each block. Ideally, output from\n * this class should keep the original control flow, while removing the\n * if/else-if/else statements.\n */\nclass StatementCombiner {\n private blocks: ConditionalBlock[] = [];\n\n get currentBlock(): undefined | ConditionalBlock {\n if (this.blocks.length === 0) {\n return undefined;\n }\n return this.blocks[this.blocks.length - 1];\n }\n\n /**\n * Creates a new block, based on the keyword type.\n */\n newBlock(keywordType: 'if_statement' | 'else_if_clause' | 'else_clause') {\n this.blocks.push(ConditionalBlock.create(keywordType));\n }\n\n /**\n * Appends a node to the current block. Nodes should be non-leaf nodes for the\n * most part because the `build()` method will use the `node.text` property to\n * build combined strings. More specifically, the node's that are appended\n * should group together child sections of each segment of the conditional\n * sequence per if/else-if/else block.\n * ___\n * The supported possibilities for `node.type` are: `command`, `comment`, or `conditional_execution`\n * ___\n * NOTE: not calling `newBlock()` before this method will throw an error.\n * ___\n * @param node the node to append on the block's body.\n */\n appendCommand(node: SyntaxNode) {\n if (!this.currentBlock) {\n throw new Error('Cannot append command to non-existent block, please create a new block first');\n }\n this.currentBlock.body.push(node);\n }\n\n /**\n * Helper for retrieving the prefix combiner for a block, based on its keyword.\n * The prefix is then used to combine the if/else-if/else blocks together.\n * ___\n * `if_statement` -> ''\n * `else_if_clause` -> 'or '\n * `else_clause` -> 'or '\n * ___\n * @param block The block to get the combiner for (which is the prefix )\n * @returns The prefix/combiner for the block\n */\n private getCombinerFromKeyword(block: ConditionalBlock) {\n switch (block.keyword) {\n case 'if_statement':\n return '';\n case 'else_if_clause':\n case 'else_clause':\n return 'or ';\n }\n }\n\n /**\n * Builds the string representation of a block, including the combiner and the comments\n * @param block The block to build the string for\n * @returns The string representation of the block\n */\n private buildBlockString(block: ConditionalBlock) {\n let str = this.getCombinerFromKeyword(block);\n block.body.forEach((node, idx) => {\n const nextNode = block.body.length - 1 >= idx\n ? block.body[idx + 1]\n : undefined;\n\n if (nextNode && nextNode.type === 'comment') {\n str += node.text + '\\n';\n } else if (nextNode && nextNode.type === 'command') {\n str += node.text + '\\nand ';\n } else {\n str += node.text + '\\n';\n }\n });\n return str;\n }\n\n /**\n * Builds the combined string of all the blocks\n */\n build() {\n return this.blocks\n .map(block => this.buildBlockString(block))\n .join('\\n')\n .trim();\n }\n}\n"
},
{
"path": "src/code-actions/disable-actions.ts",
"content": "// src/code-actions/disable-diagnostics.ts\nimport { CodeAction, Diagnostic, DiagnosticSeverity, TextEdit } from 'vscode-languageserver';\nimport { LspDocument } from '../document';\nimport { ErrorCodes } from '../diagnostics/error-codes';\nimport { SupportedCodeActionKinds } from './action-kinds';\nimport { logger } from '../logger';\n\ninterface DiagnosticGroup {\n startLine: number;\n endLine: number;\n diagnostics: Diagnostic[];\n}\n\nfunction createDisableAction(\n title: string,\n document: LspDocument,\n edits: TextEdit[],\n diagnostics: Diagnostic[],\n isPreferred: boolean = false,\n): CodeAction {\n return {\n title,\n kind: SupportedCodeActionKinds.Disable,\n edit: {\n changes: {\n [document.uri]: edits,\n },\n },\n diagnostics,\n isPreferred,\n };\n}\n\nexport function handleDisableSingleLine(\n document: LspDocument,\n diagnostic: Diagnostic,\n): CodeAction {\n const indent = document.getIndentAtLine(diagnostic.range.start.line);\n // Insert disable comment above the diagnostic line\n const edit = TextEdit.insert(\n { line: diagnostic.range.start.line, character: 0 },\n `${indent}# @fish-lsp-disable-next-line ${diagnostic.code}\\n`,\n );\n\n const severity = ErrorCodes.getSeverityString(diagnostic.severity);\n\n return createDisableAction(\n `Disable ${severity} diagnostic ${diagnostic.code} for line ${diagnostic.range.start.line + 1}`,\n document,\n [edit],\n [diagnostic],\n );\n}\n\nexport function handleDisableBlock(\n document: LspDocument,\n group: DiagnosticGroup,\n): CodeAction {\n const numbers = Array.from(new Set(group.diagnostics.map(diagnostic => diagnostic.code)).values()).join(' ');\n const startIndent = document.getIndentAtLine(group.startLine);\n const endIndent = document.getIndentAtLine(group.endLine);\n const edits = [\n // Insert disable comment at start of block\n TextEdit.insert(\n { line: group.startLine, character: 0 },\n `${startIndent}# @fish-lsp-disable ${numbers}\\n`,\n ),\n // Insert enable comment after end of block\n TextEdit.insert(\n { line: group.endLine + 1, character: 0 },\n `${endIndent}# @fish-lsp-enable ${numbers}\\n`,\n ),\n ];\n\n return {\n ...createDisableAction(\n `Disable diagnostics ${numbers} in block (lines ${group.startLine + 1}-${group.endLine + 1})`,\n document,\n edits,\n group.diagnostics,\n ),\n };\n}\n\n// Group diagnostics that are adjacent or within N lines of each other\nexport function groupDiagnostics(diagnostics: Diagnostic[], maxGap: number = 1): DiagnosticGroup[] {\n if (diagnostics.length === 0) return [];\n\n // Sort diagnostics by starting line\n const sorted = [...diagnostics].sort((a, b) =>\n a.range.start.line - b.range.start.line,\n );\n\n const groups: DiagnosticGroup[] = [];\n let currentGroup: DiagnosticGroup = {\n startLine: sorted[0]!.range.start.line,\n endLine: sorted[0]!.range.end.line,\n diagnostics: [sorted[0]!],\n };\n\n for (let i = 1; i < sorted.length; i++) {\n const current = sorted[i]!;\n const gap = current.range.start.line - currentGroup.endLine;\n\n if (gap <= maxGap) {\n // Add to current group\n currentGroup.endLine = Math.max(currentGroup.endLine, current.range.end.line);\n currentGroup.diagnostics.push(current);\n } else {\n // Start new group\n groups.push(currentGroup);\n currentGroup = {\n startLine: current.range.start.line,\n endLine: current.range.end.line,\n diagnostics: [current],\n };\n }\n }\n\n // Add final group\n groups.push(currentGroup);\n\n return groups;\n}\n\nexport function handleDisableEntireFile(\n document: LspDocument,\n diagnostics: Diagnostic[],\n): CodeAction[] {\n const results: CodeAction[] = [];\n const diagnosticsCounts = new Map();\n diagnostics.forEach(diagnostic => {\n if (ErrorCodes.codeTypeGuard(diagnostic.code)) {\n const code = ErrorCodes.getDiagnostic(diagnostic.code).code;\n diagnosticsCounts.set(code, (diagnosticsCounts.get(code) || 0) + 1);\n }\n });\n\n const matchingDiagnostics: Array = [];\n diagnosticsCounts.forEach((count, code) => {\n if (count >= 5) {\n logger.log(`CODEACTION: Disabling ${count} ${code.toString()} diagnostics in file`);\n }\n matchingDiagnostics.push(code as ErrorCodes.CodeTypes);\n });\n\n if (matchingDiagnostics.length === 0) return results;\n\n let tokenLine = 0;\n let firstLine = document.getLine(tokenLine);\n if (firstLine.startsWith('#!/')) {\n tokenLine++;\n }\n firstLine = document.getLine(tokenLine);\n const allNumbersStr = matchingDiagnostics.join(' ').trim();\n if (!firstLine.startsWith('# @fish-lsp-disable')) {\n const edits = [\n TextEdit.insert(\n { line: tokenLine, character: 0 },\n `# @fish-lsp-disable ${allNumbersStr}\\n`,\n ),\n ];\n\n results.push(\n createDisableAction(\n `Disable all diagnostics in file (${allNumbersStr.split(' ').join(', ')})`,\n document,\n edits,\n diagnostics,\n ),\n );\n\n matchingDiagnostics.forEach(match => {\n const severity = ErrorCodes.getSeverityString(ErrorCodes.getDiagnostic(match).severity);\n results.push(\n createDisableAction(\n `Disable ${severity} ${match.toString()} diagnostics for entire file`,\n document,\n [\n TextEdit.insert({ line: tokenLine, character: 0 },\n `# @fish-lsp-disable ${match.toString()}\\n`),\n ],\n diagnostics,\n ),\n );\n });\n }\n\n return results;\n}\n\nexport function getDisableDiagnosticActions(\n document: LspDocument,\n diagnostics: Diagnostic[],\n): CodeAction[] {\n const actions: CodeAction[] = [];\n\n const fixedDiagnostics = diagnostics\n .filter(diagnostic => !!diagnostic?.severity)\n .filter(diagnostic =>\n diagnostic?.source === 'fish-lsp' && diagnostic?.code !== ErrorCodes.invalidDiagnosticCode,\n );\n\n // Add single-line disable actions for each diagnostic\n fixedDiagnostics\n .filter(diagnostic =>\n diagnostic?.severity === DiagnosticSeverity.Warning\n || diagnostic.code === ErrorCodes.sourceFileDoesNotExist,\n ).forEach(diagnostic => {\n actions.push(handleDisableSingleLine(document, diagnostic));\n });\n\n // Add block disable actions for groups\n const groups = groupDiagnostics(fixedDiagnostics);\n groups.forEach(group => {\n // Only create block actions for multiple diagnostics\n if (group.diagnostics.length > 1) {\n actions.push(handleDisableBlock(document, group));\n }\n });\n actions.push(...handleDisableEntireFile(document, fixedDiagnostics));\n return actions;\n}\n"
},
{
"path": "src/code-actions/quick-fixes.ts",
"content": "import { ChangeAnnotation, CodeAction, Diagnostic, RenameFile, TextEdit, WorkspaceEdit } from 'vscode-languageserver';\nimport { LspDocument } from '../document';\nimport { ErrorCodes } from '../diagnostics/error-codes';\nimport { equalRanges, getChildNodes } from '../utils/tree-sitter';\nimport { SyntaxNode } from 'web-tree-sitter';\nimport { ErrorNodeTypes, getFishBuiltinEquivalentCommandName } from '../diagnostics/node-types';\nimport { SupportedCodeActionKinds } from './action-kinds';\nimport { logger } from '../logger';\nimport { analyzer, Analyzer } from '../analyze';\nimport { getRange } from '../utils/tree-sitter';\nimport { pathToRelativeFunctionName, uriToPath, uriToReadablePath } from '../utils/translation';\nimport { FishString } from '../parsing/string';\nimport { findParentCommand, isAliasDefinitionName, isArgparseVariableDefinitionName, isConditionalCommand, isFunctionDefinition, isFunctionDefinitionName, isVariableDefinitionName } from '../utils/node-types';\n\n/**\n * These quick-fixes are separated from the other diagnostic quick-fixes because\n * future work will involve adding significantly more complex\n * solutions here (atleast I hope. I definitely think fish uniquely has a lot\n * of potential for how advancded quickfixes could become eventually).\n *\n * The quick-fixes located at disable-actions.ts are mainly for simple disabling\n * of diagnostic messages.\n */\n\n// Helper to create a QuickFix code action\nfunction createQuickFix(\n title: string,\n diagnostic: Diagnostic,\n edits: { [uri: string]: TextEdit[]; },\n): CodeAction {\n return {\n title,\n kind: SupportedCodeActionKinds.QuickFix.toString(),\n isPreferred: true,\n diagnostics: [diagnostic],\n edit: { changes: edits },\n };\n}\n\n/**\n * Helper to create a QuickFix code action for fixing all problems\n */\nexport function createFixAllAction(\n document: LspDocument,\n actions: CodeAction[],\n): CodeAction | undefined {\n if (actions.length === 0) return undefined;\n const fixableActions = actions.filter(action => {\n return action.isPreferred && action.kind === SupportedCodeActionKinds.QuickFix;\n });\n for (const fixable of fixableActions) {\n logger.info('createFixAllAction', { fixable: fixable.title });\n }\n\n if (fixableActions.length === 0) return undefined;\n const resultEdits: { [uri: string]: TextEdit[]; } = {};\n const diagnostics: Diagnostic[] = [];\n for (const action of fixableActions) {\n if (!action.edit || !action.edit.changes) continue;\n const changes = action.edit.changes;\n for (const uri of Object.keys(changes)) {\n const edits = changes[uri];\n if (!edits || edits.length === 0) continue;\n if (!resultEdits[uri]) {\n resultEdits[uri] = [];\n }\n const oldEdits = resultEdits[uri];\n if (edits && edits?.length > 0) {\n // Check each edit individually for duplicates\n // Only skip if both range AND content are identical\n for (const newEdit of edits) {\n const isDuplicate = oldEdits.some(e =>\n equalRanges(e.range, newEdit.range) && e.newText === newEdit.newText,\n );\n if (!isDuplicate) {\n oldEdits.push(newEdit);\n }\n }\n resultEdits[uri] = oldEdits;\n diagnostics.push(...action.diagnostics || []);\n }\n }\n }\n const allEdits: TextEdit[] = [];\n for (const uri in resultEdits) {\n const edits = resultEdits[uri];\n if (!edits || edits.length === 0) continue;\n allEdits.push(...edits);\n }\n return {\n title: `Fix all auto-fixable quickfixes (total fixes: ${allEdits.length}) (codes: ${diagnostics.map(d => d.code).join(', ')})`,\n kind: SupportedCodeActionKinds.QuickFixAll,\n diagnostics,\n edit: {\n changes: resultEdits,\n },\n data: {\n isQuickFix: true,\n documentUri: document.uri,\n totalEdits: allEdits.length,\n uris: Array.from(new Set(Object.keys(resultEdits))),\n },\n };\n}\n\n/**\n * utility function to get the error node token\n * Improved to handle all opening tokens defined in ErrorNodeTypes\n */\nfunction getErrorNodeToken(node: SyntaxNode): string | undefined {\n const { text, type } = node;\n\n // Handle exact node type matches first (most reliable)\n if (type in ErrorNodeTypes) {\n return ErrorNodeTypes[type as keyof typeof ErrorNodeTypes];\n }\n\n // For ERROR nodes, we need to look at the actual content to determine the token\n if (type === 'ERROR') {\n // Look for unclosed quotes at the end of the text\n if (text.endsWith('\"') && !text.startsWith('\"')) {\n return '\"';\n }\n if (text.endsWith(\"'\") && !text.startsWith(\"'\")) {\n return \"'\";\n }\n // Look for unclosed quotes at the beginning\n if (text.includes('\"') && text.indexOf('\"') === text.lastIndexOf('\"')) {\n return '\"';\n }\n if (text.includes(\"'\") && text.indexOf(\"'\") === text.lastIndexOf(\"'\")) {\n return \"'\";\n }\n }\n\n // Handle single character tokens that might be embedded in text\n const singleCharTokens = ['\"', \"'\", '{', '[', '('];\n for (const token of singleCharTokens) {\n if (text.includes(token)) {\n // Check if it's an unclosed token by counting occurrences\n let matches = 0;\n if (token === '\"') {\n matches = (text.match(/\"/g) || []).length;\n } else if (token === \"'\") {\n matches = (text.match(/'/g) || []).length;\n } else {\n matches = (text.match(new RegExp(`\\\\${token}`, 'g')) || []).length;\n }\n\n if (matches % 2 === 1) { // Odd number means unclosed\n return ErrorNodeTypes[token as keyof typeof ErrorNodeTypes];\n }\n }\n }\n\n // Handle keyword tokens (function, while, if, for, begin, switch)\n const keywordTokens = ['function', 'while', 'if', 'for', 'begin', 'switch'];\n for (const token of keywordTokens) {\n // Check if the text starts with the keyword followed by whitespace or end of string\n const regex = new RegExp(`^${token}(?=\\\\s|$)`);\n if (regex.test(text)) {\n return ErrorNodeTypes[token as keyof typeof ErrorNodeTypes];\n }\n }\n\n // Fallback to original logic for any remaining cases\n const startTokens = Object.keys(ErrorNodeTypes);\n for (const token of startTokens) {\n if (text.startsWith(token)) {\n return ErrorNodeTypes[token as keyof typeof ErrorNodeTypes];\n }\n }\n\n return undefined;\n}\n\nexport function handleMissingEndFix(\n document: LspDocument,\n diagnostic: Diagnostic,\n analyzer: Analyzer,\n): CodeAction | undefined {\n const root = analyzer.getTree(document.uri)!.rootNode;\n\n let errNode = root.descendantForPosition({ row: diagnostic.range.start.line, column: diagnostic.range.start.character })!;\n\n // If we found an ERROR node, try to find the specific error token within it\n if (errNode.type === 'ERROR') {\n // Use findErrorCause to get the specific problematic node\n const errorCause = findErrorCauseFromNode(errNode);\n if (errorCause) {\n errNode = errorCause;\n }\n }\n\n const rawErrorNodeToken = getErrorNodeToken(errNode);\n\n if (!rawErrorNodeToken) return undefined;\n\n // Determine the appropriate insertion position and text based on token type\n const insertionData = getTokenInsertionData(errNode, rawErrorNodeToken, document);\n\n return {\n title: `Add missing \"${rawErrorNodeToken}\"`,\n diagnostics: [diagnostic],\n kind: SupportedCodeActionKinds.QuickFix,\n edit: {\n changes: {\n [document.uri]: [\n TextEdit.insert(insertionData.position, insertionData.text),\n ],\n },\n },\n };\n}\n\n/**\n * Find the specific error cause within an ERROR node\n */\nfunction findErrorCauseFromNode(errorNode: SyntaxNode): SyntaxNode | null {\n // Look for unclosed quote tokens within the error node's children\n for (const child of errorNode.children) {\n if (child.type === '\"' || child.type === \"'\" || child.text === '\"' || child.text === \"'\") {\n return child;\n }\n }\n\n // If no specific token found, look at the text content\n const text = errorNode.text;\n if (text.includes('\"') && text.indexOf('\"') === text.lastIndexOf('\"')) {\n return errorNode; // Return the error node itself\n }\n if (text.includes(\"'\") && text.indexOf(\"'\") === text.lastIndexOf(\"'\")) {\n return errorNode; // Return the error node itself\n }\n\n return null;\n}\n\n/**\n * Determines the appropriate insertion position and text for different token types\n */\nfunction getTokenInsertionData(errNode: SyntaxNode, closingToken: string, document: LspDocument): {\n position: { line: number; character: number; };\n text: string;\n} {\n // Handle 'end' tokens (function, while, if, for, begin, switch)\n if (closingToken === 'end') {\n // For block statements, add 'end' on a new line with proper indentation\n const line = errNode.endPosition.row;\n const indentLevel = document.getIndentAtLine(errNode.startPosition.row);\n return {\n position: { line: line, character: errNode.endPosition.column },\n text: `\\n${indentLevel}end`,\n };\n }\n\n // Handle quotes (', \")\n if (closingToken === \"'\" || closingToken === '\"') {\n // For quotes, add the closing quote immediately after the current position\n return {\n position: { line: errNode.endPosition.row, character: errNode.endPosition.column },\n text: closingToken,\n };\n }\n\n // Handle brackets, braces, parentheses (], }, ))\n if ([')', '}', ']'].includes(closingToken)) {\n // For brackets/braces/parens, add the closing token immediately after\n return {\n position: { line: errNode.endPosition.row, character: errNode.endPosition.column },\n text: closingToken,\n };\n }\n\n // Fallback case\n return {\n position: { line: errNode.endPosition.row, character: errNode.endPosition.column },\n text: closingToken,\n };\n}\n\nexport function handleExtraEndFix(\n document: LspDocument,\n diagnostic: Diagnostic,\n): CodeAction {\n // Simply delete the extra end\n const edit = TextEdit.del(diagnostic.range);\n\n return createQuickFix(\n 'Remove extra \"end\"',\n diagnostic,\n {\n [document.uri]: [edit],\n },\n );\n}\n\n// Handle missing quiet option error\nfunction handleMissingQuietError(\n document: LspDocument,\n diagnostic: Diagnostic,\n): CodeAction | undefined {\n // Add -q flag\n const edit = TextEdit.insert(diagnostic.range.end, ' -q ');\n\n return {\n title: 'Add silence (-q) flag',\n kind: SupportedCodeActionKinds.QuickFix,\n diagnostics: [diagnostic],\n edit: {\n changes: {\n [document.uri]: [edit],\n },\n },\n command: {\n command: 'editor.action.formatDocument',\n title: 'Format Document',\n },\n isPreferred: true,\n };\n}\n\nfunction handleZeroIndexedArray(\n document: LspDocument,\n diagnostic: Diagnostic,\n): CodeAction | undefined {\n return {\n title: 'Convert zero-indexed array to one-indexed array',\n kind: SupportedCodeActionKinds.QuickFix,\n diagnostics: [diagnostic],\n edit: {\n changes: {\n [document.uri]: [\n TextEdit.del(diagnostic.range),\n TextEdit.insert(diagnostic.range.start, '1'),\n ],\n },\n },\n isPreferred: true,\n };\n}\n\nfunction handleDotSourceCommand(\n document: LspDocument,\n diagnostic: Diagnostic,\n): CodeAction | undefined {\n const edit = TextEdit.replace(diagnostic.range, 'source');\n\n return {\n title: 'Convert dot source command to source',\n kind: SupportedCodeActionKinds.QuickFix,\n diagnostics: [diagnostic],\n edit: {\n changes: {\n [document.uri]: [edit],\n },\n },\n isPreferred: true,\n };\n}\n\n// fix cases like: -xU\nfunction handleUniversalVariable(\n document: LspDocument,\n diagnostic: Diagnostic,\n): CodeAction {\n const text = document.getText(diagnostic.range);\n\n let newText = text.replace(/U/g, 'g');\n newText = newText.replace(/--universal/g, '--global');\n\n const edit = TextEdit.replace(\n {\n start: diagnostic.range.start,\n end: diagnostic.range.end,\n },\n newText,\n );\n\n return {\n title: 'Convert universal scope to global scope',\n kind: SupportedCodeActionKinds.QuickFix,\n diagnostics: [diagnostic],\n edit: {\n changes: {\n [document.uri]: [edit],\n },\n },\n isPreferred: true,\n };\n}\n\nfunction handleExternalShellCommandInsteadOfBuiltin(\n document: LspDocument,\n diagnostic: Diagnostic,\n): CodeAction | undefined {\n // Replace the command with an external shell command\n const node = analyzer.nodeAtPoint(document.uri, diagnostic.range.start.line, diagnostic.range.start.character);\n if (!node) {\n logger.warning('handleExternalShellCommandInsteadOfBuiltin: No node found for diagnostic', diagnostic);\n return undefined;\n }\n const newCommandText = getFishBuiltinEquivalentCommandName(node);\n if (!newCommandText) {\n logger.warning('handleExternalShellCommandInsteadOfBuiltin: No equivalent command found for', node.text);\n return undefined;\n }\n // Don't handle ambiguous commands\n if (newCommandText.includes(' | ')) {\n logger.warning('handleExternalShellCommandInsteadOfBuiltin: Command is ambiguous, skipping', newCommandText);\n return undefined;\n }\n const edit = TextEdit.replace(\n diagnostic.range,\n newCommandText,\n );\n\n return {\n title: `Convert external shell command \"${node.text}\" to fish builtin \"${newCommandText}\"`,\n kind: SupportedCodeActionKinds.QuickFix,\n diagnostics: [diagnostic],\n edit: {\n changes: {\n [document.uri]: [edit],\n },\n },\n isPreferred: true,\n };\n}\n\nexport function handleSingleQuoteVarFix(\n document: LspDocument,\n diagnostic: Diagnostic,\n): CodeAction {\n // Replace single quotes with double quotes\n const text = document.getText(diagnostic.range);\n const newText = text.replace(/\\\\/g, '\\\\\\\\').replace(/'/g, '\"').replace(/\\$/g, '\\\\$');\n\n const edit = TextEdit.replace(\n diagnostic.range,\n newText,\n );\n\n return {\n title: 'Convert to double quotes',\n kind: SupportedCodeActionKinds.QuickFix,\n diagnostics: [diagnostic],\n edit: {\n changes: {\n [document.uri]: [edit],\n },\n },\n isPreferred: true,\n };\n}\n\nexport function handleTestCommandVariableExpansionWithoutString(\n document: LspDocument,\n diagnostic: Diagnostic,\n): CodeAction {\n return createQuickFix(\n 'Surround test string comparison with double quotes',\n diagnostic,\n {\n [document.uri]: [\n TextEdit.insert(diagnostic.range.start, '\"'),\n TextEdit.insert(diagnostic.range.end, '\"'),\n ],\n },\n );\n}\n\nfunction handleMissingDefinition(diagnostic: Diagnostic, node: SyntaxNode, document: LspDocument): CodeAction {\n // Create function definition with filename\n const functionName = pathToRelativeFunctionName(document.uri);\n const edit: TextEdit = {\n range: {\n start: { line: 0, character: 0 },\n end: { line: 0, character: 0 },\n },\n newText: `function ${functionName}\\n # TODO: Implement function\\nend\\n`,\n };\n\n return {\n title: `Create function '${functionName}'`,\n kind: SupportedCodeActionKinds.QuickFix,\n diagnostics: [diagnostic],\n edit: {\n changes: {\n [document.uri]: [edit],\n },\n },\n isPreferred: true,\n };\n}\n\nfunction handleFilenameMismatch(diagnostic: Diagnostic, node: SyntaxNode, document: LspDocument): CodeAction | undefined {\n const functionName = node.text;\n const newUri = document.uri.replace(/[^/]+\\.fish$/, `${functionName}.fish`);\n if (document.getAutoloadType() !== 'functions') {\n return;\n }\n const oldName = document.getAutoLoadName();\n const oldFilePath = document.getFilePath();\n const oldFilename = document.getFilename();\n const newFilePath = uriToPath(newUri);\n\n const annotation = ChangeAnnotation.create(\n `rename ${oldFilename} to ${newUri.split('/').pop()}`,\n true,\n `Rename '${oldFilePath}' to '${newFilePath}'`,\n );\n\n const workspaceEdit: WorkspaceEdit = {\n documentChanges: [\n RenameFile.create(document.uri, newUri, { ignoreIfExists: false, overwrite: true }),\n ],\n changeAnnotations: {\n [annotation.label]: annotation,\n },\n };\n\n return {\n title: `RENAME: '${oldFilename}' to '${functionName}.fish' (File missing function '${oldName}')`,\n kind: SupportedCodeActionKinds.RefactorRewrite,\n diagnostics: [diagnostic],\n edit: workspaceEdit,\n };\n}\n\nfunction handleCompletionFilenameMismatch(diagnostic: Diagnostic, node: SyntaxNode, document: LspDocument): CodeAction | undefined {\n const functionName = FishString.fromNode(node);\n const newUri = document.uri.replace(/[^/]+\\.fish$/, `${functionName}.fish`);\n if (document.getAutoloadType() !== 'completions') {\n return;\n }\n const oldName = document.getAutoLoadName();\n const oldFilePath = document.getFilePath();\n const oldFilename = document.getFilename();\n const newFilePath = uriToPath(newUri);\n\n const annotation = ChangeAnnotation.create(\n `rename ${oldFilename} to ${newUri.split('/').pop()}`,\n true,\n `Rename '${oldFilePath}' to '${newFilePath}'`,\n );\n\n const workspaceEdit: WorkspaceEdit = {\n documentChanges: [\n RenameFile.create(document.uri, newUri, { ignoreIfExists: false, overwrite: true }),\n ],\n changeAnnotations: {\n [annotation.label]: annotation,\n },\n };\n\n return {\n title: `RENAME: '${oldFilename}' to '${functionName}.fish' (File missing completion '${oldName}')`,\n kind: SupportedCodeActionKinds.RefactorRewrite,\n diagnostics: [diagnostic],\n edit: workspaceEdit,\n };\n}\nfunction handleReservedKeyword(diagnostic: Diagnostic, node: SyntaxNode, document: LspDocument): CodeAction {\n const replaceText = `__${node.text}`;\n\n const changeAnnotation = ChangeAnnotation.create(\n `rename ${node.text} to ${replaceText}`,\n true,\n `Rename reserved keyword function definition '${node.text}' to '${replaceText}' (line: ${node.startPosition.row + 1})`,\n );\n\n const workspaceEdit: WorkspaceEdit = {\n changes: {\n [document.uri]: [\n TextEdit.replace(getRange(node), replaceText),\n ],\n },\n changeAnnotations: {\n [changeAnnotation.label]: changeAnnotation,\n },\n };\n return {\n title: `Rename reserved keyword '${node.text}' to '${replaceText}' (line: ${node.startPosition.row + 1})`,\n kind: SupportedCodeActionKinds.QuickFix,\n diagnostics: [diagnostic],\n isPreferred: true,\n edit: workspaceEdit,\n };\n}\n\nconst getNodeType = (node: SyntaxNode) => {\n if (isFunctionDefinitionName(node)) {\n return 'function';\n }\n if (isArgparseVariableDefinitionName(node)) {\n return 'argparse';\n }\n if (isAliasDefinitionName(node)) {\n return 'alias';\n }\n if (isVariableDefinitionName(node)) {\n return 'variable';\n }\n return 'unknown';\n};\n\nfunction handleUnusedSymbol(diagnostic: Diagnostic, node: SyntaxNode, document: LspDocument): CodeAction | undefined {\n const nodeType = getNodeType(node);\n if (nodeType === 'unknown') return undefined;\n\n // Find the entire function definition to remove\n let scopeNode = node;\n while (scopeNode && !isFunctionDefinition(scopeNode)) {\n scopeNode = scopeNode.parent!;\n }\n\n if (nodeType === 'function') {\n const changeAnnotation = ChangeAnnotation.create(\n `Removed unused function ${node.text}`,\n true,\n `Removed unused function '${node.text}', in file '${document.getFilePath()}' (line: ${node.startPosition.row + 1} - ${node.endPosition.row + 1})`,\n );\n\n const workspaceEdit: WorkspaceEdit = {\n changes: {\n [document.uri]: [\n TextEdit.del(getRange(scopeNode)),\n ],\n },\n changeAnnotations: {\n [changeAnnotation.label]: changeAnnotation,\n },\n };\n\n return {\n title: `Remove unused function ${node.text} (line: ${node.startPosition.row + 1})`,\n kind: SupportedCodeActionKinds.QuickFix,\n diagnostics: [diagnostic],\n edit: workspaceEdit,\n };\n }\n if (nodeType === 'argparse') {\n const parentCommand = findParentCommand(node);\n if (!parentCommand) return undefined;\n\n const changeAnnotation = ChangeAnnotation.create(\n `Check if argparse variable ${node.text} is set`,\n true,\n `Check if argparse variable '${node.text}' is set, in file '${document.getFilePath()}' (line: ${node.startPosition.row + 1})`,\n );\n\n const symbol = analyzer.getDefinition(document, diagnostic.range.end);\n if (!symbol) return undefined;\n\n const indent = document.getIndentAtLine(parentCommand.endPosition.row);\n const name = symbol.aliasedNames.length > 0\n ? symbol.aliasedNames.reduce((longest, current) => current.length > longest.length ? current : longest, '')\n : symbol.name;\n const insertText = [\n '\\n',\n `if set -ql ${name}`,\n ' ',\n 'end',\n ].map(line => `${indent}${line}`).join('\\n');\n\n let parentNode = symbol.node;\n if (parentNode && parentNode.nextNamedSibling && isConditionalCommand(parentNode.nextNamedSibling)) {\n while (parentNode && parentNode.nextNamedSibling && isConditionalCommand(parentNode.nextNamedSibling)) {\n parentNode = parentNode.nextNamedSibling;\n }\n }\n\n const workspaceEdit: WorkspaceEdit = {\n changes: {\n [document.uri]: [\n TextEdit.insert(getRange(parentNode).end, insertText),\n ],\n },\n changeAnnotations: {\n [changeAnnotation.label]: changeAnnotation,\n },\n };\n return {\n title: `Use \\`argparse ${node.text}\\` variable '${name}' if it's set in '${symbol.parent?.name || uriToReadablePath(document.uri)}'`,\n kind: SupportedCodeActionKinds.QuickFix,\n diagnostics: [diagnostic],\n edit: workspaceEdit,\n isPreferred: true,\n };\n }\n return undefined;\n}\n\nfunction handleAddEndStdinToArgparse(diagnostic: Diagnostic, document: LspDocument): CodeAction {\n const edit = TextEdit.insert(diagnostic.range.end, ' -- $argv');\n\n return {\n title: 'Add end stdin ` -- $argv` to argparse',\n kind: SupportedCodeActionKinds.QuickFix,\n diagnostics: [diagnostic],\n edit: {\n changes: {\n [document.uri]: [edit],\n },\n },\n isPreferred: true,\n };\n}\n\nfunction handleConvertDeprecatedFishLsp(diagnostic: Diagnostic, node: SyntaxNode, document: LspDocument): CodeAction {\n // const value = document.getText(diagnostic.range);\n logger.log({ name: 'handleConvertDeprecatedFishLsp', diagnostic: diagnostic.range, node: node.text });\n\n const replaceText = node.text === 'fish_lsp_logfile' ? 'fish_lsp_log_file' : node.text;\n const edit = TextEdit.replace(diagnostic.range, replaceText);\n const workspaceEdit: WorkspaceEdit = {\n changes: {\n [document.uri]: [edit],\n },\n };\n return {\n title: 'Convert deprecated environment variable name',\n kind: SupportedCodeActionKinds.QuickFix,\n diagnostics: [diagnostic],\n edit: workspaceEdit,\n isPreferred: true,\n };\n}\n\nexport async function getQuickFixes(\n document: LspDocument,\n diagnostic: Diagnostic,\n analyzer: Analyzer,\n): Promise {\n if (!diagnostic.code) return [];\n\n logger.log({\n code: diagnostic.code,\n message: diagnostic.message,\n severity: diagnostic.severity,\n node: diagnostic.data.node.text,\n range: diagnostic.range,\n });\n\n let action: CodeAction | undefined;\n const actions: CodeAction[] = [];\n\n const root = analyzer.getRootNode(document.uri);\n let node = root;\n\n if (root) {\n node = getChildNodes(root).find(n =>\n n.startPosition.row === diagnostic.range.start.line &&\n n.startPosition.column === diagnostic.range.start.character);\n }\n logger.info('getQuickFixes', { code: diagnostic.code, message: diagnostic.message, node: node?.text });\n\n switch (diagnostic.code) {\n case ErrorCodes.missingEnd:\n action = handleMissingEndFix(document, diagnostic, analyzer);\n if (action) actions.push(action);\n return actions;\n\n case ErrorCodes.extraEnd:\n action = handleExtraEndFix(document, diagnostic);\n if (action) actions.push(action);\n return actions;\n\n case ErrorCodes.missingQuietOption:\n action = handleMissingQuietError(document, diagnostic);\n if (action) actions.push(action);\n return actions;\n\n case ErrorCodes.usedUnviersalDefinition:\n action = handleUniversalVariable(document, diagnostic);\n if (action) actions.push(action);\n return actions;\n\n case ErrorCodes.usedExternalShellCommandWhenBuiltinExists:\n action = handleExternalShellCommandInsteadOfBuiltin(document, diagnostic);\n if (action) actions.push(action);\n return actions;\n\n case ErrorCodes.dotSourceCommand:\n action = handleDotSourceCommand(document, diagnostic);\n if (action) actions.push(action);\n return actions;\n\n case ErrorCodes.zeroIndexedArray:\n action = handleZeroIndexedArray(document, diagnostic);\n if (action) actions.push(action);\n return actions;\n\n case ErrorCodes.singleQuoteVariableExpansion:\n action = handleSingleQuoteVarFix(document, diagnostic);\n if (action) actions.push(action);\n return actions;\n\n case ErrorCodes.testCommandMissingStringCharacters:\n action = handleTestCommandVariableExpansionWithoutString(document, diagnostic);\n if (action) actions.push(action);\n return actions;\n\n case ErrorCodes.autoloadedFunctionMissingDefinition:\n if (!node) return [];\n return [handleMissingDefinition(diagnostic, node, document)];\n case ErrorCodes.autoloadedFunctionFilenameMismatch:\n if (!node) return [];\n action = handleFilenameMismatch(diagnostic, node, document);\n if (action) actions.push(action);\n return actions;\n case ErrorCodes.functionNameUsingReservedKeyword:\n if (!node) return [];\n return [handleReservedKeyword(diagnostic, node, document)];\n // case ErrorCodes.unusedLocalFunction:\n // if (!node) return [];\n // return [handleUnusedFunction(diagnostic, node, document)];\n case ErrorCodes.unusedLocalDefinition:\n if (!node) return [];\n action = handleUnusedSymbol(diagnostic, node, document);\n if (action) actions.push(action);\n return actions;\n\n case ErrorCodes.autoloadedCompletionMissingCommandName:\n if (!node) return [];\n action = handleCompletionFilenameMismatch(diagnostic, node, document);\n if (action) actions.push(action);\n return actions;\n\n case ErrorCodes.argparseMissingEndStdin:\n action = handleAddEndStdinToArgparse(diagnostic, document);\n if (action) actions.push(action);\n return actions;\n\n case ErrorCodes.fishLspDeprecatedEnvName:\n if (!node) return [];\n return [handleConvertDeprecatedFishLsp(diagnostic, node, document)];\n\n default:\n return actions;\n }\n}\n"
},
{
"path": "src/code-actions/redirect-actions.ts",
"content": "import { TextEdit } from 'vscode-languageserver';\nimport { SyntaxNode } from 'web-tree-sitter';\nimport { LspDocument } from '../document';\nimport { logger } from '../logger';\nimport { createRefactorAction } from './refactors';\nimport { SupportedCodeActionKinds } from './action-kinds';\nimport { findParentCommand, isCommand } from '../utils/node-types';\n\nfunction selectCommandNode(node: SyntaxNode): SyntaxNode | null {\n let cmd = node;\n if (node.type !== 'command') {\n cmd = findParentCommand(node) || node;\n }\n if (!cmd || !isCommand(cmd)) return null;\n return cmd;\n}\n\nexport function silenceCommandAction(\n document: LspDocument,\n selectedNode: SyntaxNode,\n) {\n logger.log('silence command', { document: document.uri }, { selectedNode: { text: selectedNode.text, type: selectedNode.type } });\n\n const cmd = selectCommandNode(selectedNode);\n if (!cmd) return;\n\n const insertEdit = TextEdit.insert(\n { line: cmd.endPosition.row, character: cmd.endPosition.column },\n ' &>/dev/null',\n );\n\n return createRefactorAction(\n `Silence command '${cmd.firstNamedChild!.text} &>/dev/null' (line: ${cmd.startPosition.row + 1})`,\n SupportedCodeActionKinds.RefactorRewrite,\n {\n [document.uri]: [insertEdit],\n },\n );\n}\n\nexport function silenceStderrCommandAction(\n document: LspDocument,\n selectedNode: SyntaxNode,\n) {\n logger.log('silence stderr command', { document: document.uri }, { selectedNode: { text: selectedNode.text, type: selectedNode.type } });\n\n const cmd = selectCommandNode(selectedNode);\n if (!cmd) return;\n\n const insertEdit = TextEdit.insert(\n { line: cmd.endPosition.row, character: cmd.endPosition.column },\n ' 2>/dev/null',\n );\n\n return createRefactorAction(\n `Silence stderr of command '${cmd.firstNamedChild!.text} 2>/dev/null' (line: ${cmd.startPosition.row + 1})`,\n SupportedCodeActionKinds.RefactorRewrite,\n {\n [document.uri]: [insertEdit],\n },\n );\n}\n\nexport function silenceStdoutCommandAction(\n document: LspDocument,\n selectedNode: SyntaxNode,\n) {\n logger.log('silence stdout command', { document: document.uri }, { selectedNode: { text: selectedNode.text, type: selectedNode.type } });\n\n const cmd = selectCommandNode(selectedNode);\n if (!cmd) return;\n\n const insertEdit = TextEdit.insert(\n { line: cmd.endPosition.row, character: cmd.endPosition.column },\n ' >/dev/null',\n );\n\n return createRefactorAction(\n `Silence stdout of command '${cmd.firstNamedChild!.text} >/dev/null' (line: ${cmd.startPosition.row + 1})`,\n SupportedCodeActionKinds.RefactorRewrite,\n {\n [document.uri]: [insertEdit],\n },\n );\n}\n\nexport function redirectStoutToStder(\n document: LspDocument,\n selectedNode: SyntaxNode,\n) {\n logger.log('redirect stdout to stderr command', { document: document.uri }, { selectedNode: { text: selectedNode.text, type: selectedNode.type } });\n\n const cmd = selectCommandNode(selectedNode);\n if (!cmd) return;\n\n const insertEdit = TextEdit.insert(\n { line: cmd.endPosition.row, character: cmd.endPosition.column },\n ' >&2',\n );\n\n return createRefactorAction(\n `Redirect stdout to stderr of command '${cmd.firstNamedChild!.text} >&2' (line: ${cmd.startPosition.row + 1})`,\n SupportedCodeActionKinds.RefactorRewrite,\n {\n [document.uri]: [insertEdit],\n },\n );\n}\n\nexport function handleRedirectActions(\n document: LspDocument,\n selectedNode: SyntaxNode,\n) {\n const actions = [];\n\n const silenceAction = silenceCommandAction(document, selectedNode);\n if (silenceAction) actions.push(silenceAction);\n\n const silenceStderrAction = silenceStderrCommandAction(document, selectedNode);\n if (silenceStderrAction) actions.push(silenceStderrAction);\n\n const silenceStdoutAction = silenceStdoutCommandAction(document, selectedNode);\n if (silenceStdoutAction) actions.push(silenceStdoutAction);\n\n const redirectStdoutAction = redirectStoutToStder(document, selectedNode);\n if (redirectStdoutAction) actions.push(redirectStdoutAction);\n\n return actions;\n}\n"
},
{
"path": "src/code-actions/refactors.ts",
"content": "import os from 'os';\nimport { ChangeAnnotation, CodeAction, CodeActionKind, CreateFile, Range, TextDocumentEdit, TextEdit, VersionedTextDocumentIdentifier, WorkspaceEdit } from 'vscode-languageserver';\nimport { LspDocument } from '../document';\nimport { SyntaxNode } from 'web-tree-sitter';\nimport { findEnclosingScope, getChildNodes, getRange } from '../utils/tree-sitter';\nimport { findParentCommand, isBlock, isCommand, isCommandWithName, isFunctionDefinitionName, isIfStatement, isPathNode, isProgram, isStatement } from '../utils/node-types';\nimport { SupportedCodeActionKinds } from './action-kinds';\nimport { convertIfToCombinersString } from './combiner';\nimport path from 'path';\nimport { formatTextWithIndents, pathToUri, uriToReadablePath } from '../utils/translation';\nimport { logger } from '../logger';\nimport { buildCompleteString, findFlagsToComplete } from './argparse-completions';\nimport { analyzer } from '../analyze';\nimport { env } from '../utils/env-manager';\nimport { getParentCommandNodeForCodeAction } from './code-action-handler';\n\n/**\n * Notice how this file compared to the other code-actions, uses a node as it's parameter\n * This is because the reafactors are not based on diagnostics. However, if we need to use\n * a diagnostic for some reason, we can always pass its `Document.data.node` property.\n *\n * This section is very much still a WIP, so there are definitely some improvements\n * to be made.\n */\n\nexport function createRefactorAction(\n title: string,\n kind: CodeActionKind,\n edits: { [uri: string]: TextEdit[]; },\n preferredAction = false,\n): CodeAction {\n return {\n title,\n kind,\n edit: { changes: edits },\n isPreferred: preferredAction,\n };\n}\n\nexport function extractFunctionWithArgparseToCompletionsFile(\n document: LspDocument,\n range: Range,\n node: SyntaxNode,\n) {\n logger.log('extractFunctionWithArgparseToCompletionsFile', { document: document.uri }, range, { node: { text: node.text, type: node.type } });\n\n let selectedNode = node;\n if (isFunctionDefinitionName(node)) {\n selectedNode = node.parent!;\n }\n if (isCommandWithName(selectedNode, 'argparse') || selectedNode.text.startsWith('argparse')) {\n selectedNode = findEnclosingScope(selectedNode);\n }\n if (selectedNode.type !== 'function_definition') return;\n const argparseNode = getChildNodes(selectedNode).find(n => isCommandWithName(n, 'argparse'));\n const hasArgparse = !!argparseNode;\n if (!hasArgparse) return;\n\n const functionName = getChildNodes(selectedNode).find(n => isFunctionDefinitionName(n))!.text;\n const autoloadType = document.getAutoloadType();\n /** cancel if we're not in an autoloaded file */\n if (functionName !== document.getAutoLoadName() || !['functions', 'config.fish'].includes(autoloadType)) return;\n\n const completionPath = path.join(os.homedir(), '.config', 'fish', 'completions', `${functionName}.fish`);\n const completionUri = pathToUri(completionPath);\n const completionFlags = findFlagsToComplete(argparseNode);\n const completionText = buildCompleteString(functionName, completionFlags);\n const shortPath = uriToReadablePath(completionPath);\n\n const changeAnnotation: ChangeAnnotation = {\n label: `Create completions for '${functionName}' in file: ${shortPath}`,\n description: `Create completions for '${functionName}' to file: ${shortPath}`,\n };\n\n const createFileAction = CreateFile.create(completionUri, { ignoreIfExists: true, overwrite: false });\n\n // Get the selected text\n const selectedText = `\\n# auto generated by fish-lsp\\n${completionText}\\n`;\n const createFileEdit = TextDocumentEdit.create(\n VersionedTextDocumentIdentifier.create(completionUri, 0),\n [TextEdit.insert({ line: 0, character: 0 }, selectedText)]);\n\n const workspaceEdit: WorkspaceEdit = {\n documentChanges: [\n createFileAction,\n createFileEdit,\n ],\n changeAnnotations: { [changeAnnotation.label]: changeAnnotation },\n };\n\n return {\n title: `Create completions for '${functionName}' in file: ${shortPath}`,\n kind: SupportedCodeActionKinds.RefactorExtract,\n edit: workspaceEdit,\n } as CodeAction;\n}\n\nexport function extractFunctionToFile(\n document: LspDocument,\n range: Range,\n node: SyntaxNode,\n) {\n logger.log('extractFunctionToFile', { document: document.uri }, range, { node: { text: node.text, type: node.type } });\n\n let selectedNode = node;\n if (isFunctionDefinitionName(node)) {\n selectedNode = node.parent!;\n }\n if (selectedNode.type !== 'function_definition') return;\n\n const functionName = getChildNodes(selectedNode).find(n => isFunctionDefinitionName(n))!.text;\n // cancel if we're already in the file\n if (functionName === document.getAutoLoadName()) return;\n const functionPath = path.join(os.homedir(), '.config', 'fish', 'functions', `${functionName}.fish`);\n const functionUri = pathToUri(functionPath);\n const shortPath = uriToReadablePath(functionPath);\n\n const changeAnnotation: ChangeAnnotation = {\n label: `Extract function '${functionName}' to file: ${shortPath}`,\n description: `Extract function '${functionName}' to file: ${shortPath}`,\n };\n\n const createFileAction = CreateFile.create(functionUri, { ignoreIfExists: false, overwrite: true });\n\n // Get the selected text\n const selectedText = document.getText(getRange(selectedNode));\n const createFileEdit = TextDocumentEdit.create(\n VersionedTextDocumentIdentifier.create(functionUri, 0),\n [TextEdit.insert({ line: 0, character: 0 }, selectedText)]);\n\n const removeOldFunction = TextDocumentEdit.create(\n VersionedTextDocumentIdentifier.create(document.uri, document.version),\n [TextEdit.del(getRange(selectedNode))]);\n\n const workspaceEdit: WorkspaceEdit = {\n documentChanges: [\n createFileAction,\n createFileEdit,\n removeOldFunction,\n ],\n changeAnnotations: { [changeAnnotation.label]: changeAnnotation },\n };\n\n return {\n title: `Extract function '${functionName}' to file: ${shortPath}`,\n kind: SupportedCodeActionKinds.RefactorExtract,\n edit: workspaceEdit,\n } as CodeAction;\n}\n\nexport function extractToFunction(\n document: LspDocument,\n range: Range,\n): CodeAction | undefined {\n logger.log('extractToFunction', { document: document.uri }, { range });\n // Generate a unique function name\n const functionName = `extracted_function_${Math.floor(Math.random() * 1000)}`;\n\n // Get the selected text\n const selectedText = document.getText(range);\n // make sure we're not extracting nothing\n if (selectedText.trim() === '' && document.getLine(range.start.line).trim() !== '') return;\n\n const node = analyzer.nodeAtPoint(document.uri, range.start.line, range.start.character);\n const goodTypes = [\n isCommand,\n isBlock,\n isStatement,\n (n: SyntaxNode) => isCommandWithName(n, 'alias'),\n ];\n const badTypes = [\n isProgram,\n isFunctionDefinitionName,\n (n: SyntaxNode) => n.type === 'function_definition',\n ];\n\n const isGoodNode = (n: SyntaxNode | null) => {\n if (!n) return false;\n return goodTypes.some(fn => fn(n)) && !badTypes.some(fn => fn(n));\n };\n\n if (node && !isGoodNode(node)) {\n return undefined;\n }\n\n const indent = document.getIndentAtLine(range.start.line);\n // Create the new function\n const functionText = [\n `\\n${indent}function ${functionName}`,\n ...selectedText.split('\\n').map(line => `${indent} ${line}`), // Indent the function body\n `${indent}end\\n`,\n ].join('\\n');\n\n // Insert the new function before the current scope\n const insertEdit = TextEdit.insert(\n { line: range.start.line, character: 0 },\n `\\n${functionText}\\n`,\n );\n\n // Replace the selected text with a call to the new function\n const replaceEdit = TextEdit.replace(range, `${functionName}`);\n\n const truncatedSelectedText = selectedText.split(' ').slice(0, 2).join(' ').trimEnd();\n const msgText = truncatedSelectedText.length > 10 ? `${truncatedSelectedText.slice(0, 10)}...` : truncatedSelectedText;\n return createRefactorAction(\n `Extract '${msgText}' to local function '${functionName}' (line: ${range.start.line + 1})`,\n SupportedCodeActionKinds.RefactorExtract,\n {\n [document.uri]: [replaceEdit, insertEdit],\n },\n );\n}\n\nexport function extractCommandToFunction(\n document: LspDocument,\n selectionRange: Range | undefined,\n selectedNode: SyntaxNode,\n) {\n logger.log('extractCommandToFunction', { document: document.uri }, { selectionRange, selectedNode: { text: selectedNode.text, type: selectedNode.type } });\n // Generate a unique function name\n const functionName = `extracted_function_${Math.floor(Math.random() * 1000)}`;\n\n let extractRange: Range;\n let commandName: string;\n\n // If there's a selection, use it directly\n if (selectionRange) {\n extractRange = selectionRange;\n const selectedText = document.getText(selectionRange);\n // Try to get a meaningful name from the first few words\n const firstLine = selectedText.trim().split('\\n')[0];\n const words = firstLine?.split(/\\s+/) || [];\n commandName = words[0] || 'selection';\n } else {\n // Otherwise, fall back to finding the command node\n const parentCmd = getParentCommandNodeForCodeAction(selectedNode);\n if (parentCmd) selectedNode = parentCmd;\n if (!selectedNode || !isCommand(selectedNode)) {\n logger.warning({\n action: 'extractCommandToFunction',\n reason: 'not a command node',\n });\n return;\n }\n extractRange = getRange(selectedNode);\n commandName = selectedNode.firstNamedChild?.text || 'command';\n }\n\n // Replace the selected text with a call to the new function\n const callText = selectionRange ? `$(${functionName})` : `${functionName}`;\n const repRange = selectionRange ? selectionRange : extractRange;\n\n // Get the selected text\n const selectedText = document.getText(repRange);\n\n // Create the new function\n const functionText = [\n `\\nfunction ${functionName}`,\n ...selectedText.split('\\n').map(line => ` ${line}`), // Indent the function body\n 'end\\n',\n ].join('\\n');\n\n const replaceEdit = TextEdit.replace(repRange, callText);\n\n // Insert the new function at end of file\n const insertEdit = TextEdit.insert(\n { line: document.lineCount, character: 0 },\n `\\n${functionText}\\n`,\n );\n\n const title = selectionRange\n ? `Extract selected '${commandName}' to local function '${functionName}' (line ${extractRange.start.line + 1})`\n : `Extract selected '${commandName}' command to local function '${functionName}' (line ${extractRange.start.line + 1})`;\n\n return createRefactorAction(\n title,\n SupportedCodeActionKinds.RefactorExtract,\n {\n [document.uri]: [insertEdit, replaceEdit],\n },\n\n );\n}\n\nexport function extractToVariable(\n document: LspDocument,\n range: Range,\n selectedNode: SyntaxNode,\n): CodeAction | undefined {\n logger.log('extractToVariable', { document: document.uri }, { selectedNode: { text: selectedNode.text, type: selectedNode.type } });\n // Only allow extracting commands or expressions\n const parentCmd = getParentCommandNodeForCodeAction(selectedNode);\n if (parentCmd) selectedNode = parentCmd;\n if (!isCommand(selectedNode)) return undefined;\n\n const newRange = getRange(selectedNode);\n const selectedText = document.getText(newRange);\n const varName = `extracted_var_${Math.floor(Math.random() * 1000)}`;\n\n // Create variable declaration\n const declaration = `set -l ${varName} (${selectedText})\\n`;\n\n // Replace original text with variable\n const replaceEdit = TextEdit.replace(newRange, declaration);\n\n return createRefactorAction(\n `Extract selected '${selectedNode.firstNamedChild!.text}' command to local variable '${varName}' (line: ${newRange.start.line + 1})`,\n SupportedCodeActionKinds.RefactorExtract,\n {\n [document.uri]: [replaceEdit],\n },\n );\n}\n\nexport function convertIfToCombiners(\n document: LspDocument,\n selectedNode: SyntaxNode,\n isSelected: boolean = true,\n): CodeAction | undefined {\n logger.log('convertIfToCombiners', { uri: document.uri }, { selectedNode: { text: selectedNode.text, type: selectedNode.type } });\n let node = selectedNode;\n if (node.type === 'if' && !isIfStatement(node)) {\n node = node.parent!;\n }\n if (!isIfStatement(node)) return undefined;\n\n const combinerString = convertIfToCombinersString(node);\n // format the input with proper indentation, trimStart() because the range will include the leading whitespace\n const formattedString = formatTextWithIndents(\n document,\n selectedNode.startPosition.row,\n combinerString,\n ).trimStart();\n\n const message = isSelected ?\n `Convert selected if statement to conditionally executed statement (line: ${node.startPosition.row + 1})` :\n `Convert if statement to conditionally executed statement (line: ${node.startPosition.row + 1})`;\n\n return createRefactorAction(\n message,\n SupportedCodeActionKinds.RefactorRewrite,\n {\n [document.uri]: [TextEdit.replace(getRange(node), formattedString)],\n },\n true, // Mark as preferred action\n );\n}\n\n/**\n * Helper to check if a command is modifying PATH\n */\nfunction isPathModifyingCommand(node: SyntaxNode): boolean {\n const cmd = findParentCommand(node);\n if (!cmd) return false;\n\n const cmdName = cmd.firstNamedChild?.text;\n if (!cmdName) return false;\n\n // Check for fish_add_path command\n if (cmdName === 'fish_add_path') return true;\n\n // Check for set PATH commands\n if (cmdName === 'set') {\n const args = cmd.namedChildren.slice(1); // Skip the command name\n // Look for PATH variable being set\n for (const arg of args) {\n if (arg.text === 'PATH' || arg.text === 'path') return true;\n }\n }\n\n return false;\n}\n\nexport function replaceAbsolutePathWithVariable(\n document: LspDocument,\n range: Range,\n): CodeAction[] {\n logger.log('replaceAbsolutePathWithVariable', { document: document.uri }, range);\n const selectedText = document.getText(range);\n const node = analyzer.nodeAtPoint(document.uri, range.start.line, range.start.character);\n if (!node) return [];\n\n if (!isPathNode(node)) {\n logger.warning({\n action: 'replaceAbsolutePathWithVariable',\n reason: 'not a path node',\n nodeText: node.text,\n nodeType: node.type,\n });\n return []; // not a path node\n }\n\n if (!node.text.startsWith('/') || node.parent?.type === 'concatenation') {\n logger.warning({\n action: 'replaceAbsolutePathWithVariable',\n reason: 'not absolute path or part of concatenation',\n nodeText: node.text,\n nodeParent: {\n text: node.parent?.text,\n type: node.parent?.type,\n },\n });\n return []; // not an absolute path\n }\n\n // Check if this is a PATH-modifying command\n const isModifyingPath = isPathModifyingCommand(node);\n\n // Collect all matching variables with their array indices\n const matches: Array<{ key: string; value: string; length: number; index: number | null; }> = [];\n\n // Check each environment variable to find matching prefixes\n for (const envKey of env.keys) {\n // Skip PATH if we're in a PATH-modifying command\n if (isModifyingPath && envKey === 'PATH') continue;\n\n const envValues = env.getAsArray(envKey);\n\n for (let i = 0; i < envValues.length; i++) {\n const envValue = envValues[i];\n // Skip empty values\n if (!envValue || envValue.length === 0) continue;\n\n // Check if the absolute path starts with this environment value\n if (node.text.startsWith(envValue) && envValue.length > 1) {\n // Don't add if it's an exact match to a PATH entry when modifying PATH\n if (isModifyingPath && node.text === envValue) continue;\n\n // Store index only if the variable has multiple values (fish uses 1-based indexing)\n const arrayIndex = envValues.length > 1 ? i + 1 : null;\n\n matches.push({\n key: envKey,\n value: envValue,\n length: envValue.length,\n index: arrayIndex,\n });\n }\n }\n }\n\n // Add HOME replacement option\n const homeValue = env.get('HOME');\n if (homeValue && node.text.startsWith(homeValue)) {\n // Add $HOME option if not already in matches\n if (!matches.some(m => m.key === 'HOME')) {\n matches.push({\n key: 'HOME',\n value: homeValue,\n length: homeValue.length,\n index: null,\n });\n }\n }\n\n // Sort matches by length (longest first)\n matches.sort((a, b) => b.length - a.length);\n\n // No matches found\n if (matches.length === 0) return [];\n\n const results: CodeAction[] = [];\n const nodeRange = getRange(node);\n\n // Create code actions for each match (limit to top 5 to avoid clutter)\n const topMatches = matches.slice(0, 5);\n\n for (const match of topMatches) {\n const remainingPath = node.text.slice(match.value.length);\n const needsSlash = remainingPath.length > 0 && !remainingPath.startsWith('/');\n\n // Build variable reference with index if needed\n const varRef = match.index !== null\n ? `$${match.key}[${match.index}]`\n : `$${match.key}`;\n\n // Create replacement text\n const varReplacement = `${varRef}${needsSlash ? '/' : ''}${remainingPath}`;\n\n // Replace the entire node text (not just the matched prefix)\n results.push(createRefactorAction(\n `Replace with '${varRef}${needsSlash ? '/' : ''}...' (line: ${range.start.line + 1})`,\n SupportedCodeActionKinds.RefactorRewrite,\n {\n [document.uri]: [TextEdit.replace(nodeRange, varReplacement)],\n },\n ));\n\n // For HOME, also offer tilde (~) replacement\n if (match.key === 'HOME' && match.index === null) {\n const tildeReplacement = `~${needsSlash ? '/' : ''}${remainingPath}`;\n results.push(createRefactorAction(\n `Replace with '~${needsSlash ? '/' : ''}...' (line: ${range.start.line + 1})`,\n SupportedCodeActionKinds.RefactorRewrite,\n {\n [document.uri]: [TextEdit.replace(nodeRange, tildeReplacement)],\n },\n ));\n }\n }\n\n logger.debug({\n action: 'replaceAbsolutePathWithVariable',\n nodeText: node.text,\n selectedText,\n matches: topMatches,\n isModifyingPath,\n resultsCount: results.length,\n });\n\n return results;\n}\n\n/**\n * Simplifies set commands that manually append or prepend values\n * - set VAR $VAR appended → set -a VAR appended\n * - set VAR prepended $VAR → set --prepend VAR prepended\n */\nexport function simplifySetAppendPrepend(\n document: LspDocument,\n selectedNode: SyntaxNode,\n): CodeAction[] {\n logger.log('simplifySetAppendPrepend', { document: document.uri }, { selectedNode: { text: selectedNode.text, type: selectedNode.type } });\n\n // Find the set command\n let cmd = selectedNode;\n if (selectedNode.type !== 'command') {\n cmd = findParentCommand(selectedNode) || selectedNode;\n }\n\n if (!cmd || !isCommandWithName(cmd, 'set')) {\n return [];\n }\n\n const results: CodeAction[] = [];\n const cmdRange = getRange(cmd);\n\n // Get all named children (arguments) of the set command\n const args = cmd.namedChildren;\n if (args.length < 2) return []; // Need at least 'set' and variable name\n\n // Find where the variable name is (skip flags)\n let varNameIndex = -1;\n let varName = '';\n const flags: string[] = [];\n\n for (let i = 1; i < args.length; i++) {\n const arg = args[i];\n if (!arg) continue;\n if (arg.text.startsWith('-')) {\n flags.push(arg.text);\n } else {\n varNameIndex = i;\n varName = arg.text;\n break;\n }\n }\n\n if (varNameIndex === -1 || !varName) return [];\n\n // Get the value arguments (everything after the variable name)\n const valueArgs = args.slice(varNameIndex + 1);\n if (valueArgs.length === 0) return [];\n\n // Check for append pattern: set VAR $VAR value1 value2...\n const firstValue = valueArgs[0];\n if (!firstValue) return [];\n const isAppendPattern = firstValue.text === `$${varName}` || firstValue.text === `\\$${varName}`;\n\n // Check for prepend pattern: set VAR value1 value2... $VAR\n const lastValue = valueArgs[valueArgs.length - 1];\n if (!lastValue) return [];\n const isPrependPattern = lastValue.text === `$${varName}` || lastValue.text === `\\$${varName}`;\n\n // Append pattern: set VAR $VAR appended → set -a VAR appended\n if (isAppendPattern && valueArgs.length > 1) {\n const remainingValues = valueArgs.slice(1); // Skip $VAR\n const newFlags = [...flags, '-a'].join(' ');\n const newValues = remainingValues.map(v => v.text).join(' ');\n const replacement = `set ${newFlags} ${varName} ${newValues}`.trim().replace(/\\s+/g, ' ');\n\n results.push(createRefactorAction(\n `Simplify to 'set -a ${varName} ...' (line: ${cmdRange.start.line + 1})`,\n SupportedCodeActionKinds.RefactorRewrite,\n {\n [document.uri]: [TextEdit.replace(cmdRange, replacement)],\n },\n true, // Mark as preferred\n ));\n }\n\n // Prepend pattern: set VAR prepended $VAR → set --prepend VAR prepended\n if (isPrependPattern && valueArgs.length > 1) {\n const remainingValues = valueArgs.slice(0, -1); // Skip last $VAR\n const newFlags = [...flags, '--prepend'].join(' ');\n const newValues = remainingValues.map(v => v.text).join(' ');\n const replacement = `set ${newFlags} ${varName} ${newValues}`.trim().replace(/\\s+/g, ' ');\n\n results.push(createRefactorAction(\n `Simplify to 'set --prepend ${varName} ...' (line: ${cmdRange.start.line + 1})`,\n SupportedCodeActionKinds.RefactorRewrite,\n {\n [document.uri]: [TextEdit.replace(cmdRange, replacement)],\n },\n true, // Mark as preferred\n ));\n }\n\n logger.debug({\n action: 'simplifySetAppendPrepend',\n cmdText: cmd.text,\n varName,\n valueArgs: valueArgs.map(v => v.text),\n isAppendPattern,\n isPrependPattern,\n resultsCount: results.length,\n });\n\n return results;\n}\n"
},
{
"path": "src/code-lens.ts",
"content": "import { CodeLens } from 'vscode-languageserver';\nimport { Analyzer } from './analyze';\nimport { LspDocument } from './document';\nimport { getReferences } from './references';\nimport { uriToPath } from './utils/translation';\n\nexport function getReferenceCountCodeLenses(analyzer: Analyzer, document: LspDocument): CodeLens[] {\n const codeLenses: CodeLens[] = [];\n\n // Filter for global symbols\n const globalSymbols = analyzer.getFlatDocumentSymbols(document.uri)\n .filter(symbol => symbol.fishKind === 'FUNCTION');\n\n // Create a code lens for each global symbol\n for (const symbol of globalSymbols) {\n // Get reference count\n const references = getReferences(document, symbol.selectionRange.start) || [];\n const referencesCount = references.length;\n codeLenses.push({\n range: symbol.range,\n command: {\n title: `${referencesCount} references`,\n command: 'fish-lsp.showReferences',\n arguments: [uriToPath(document.uri), symbol.selectionRange.start, references],\n },\n });\n }\n\n return codeLenses;\n}\n"
},
{
"path": "src/command.ts",
"content": "import { Connection, ExecuteCommandParams, MessageType, /** Position, */ Range, Location, TextEdit, WorkspaceEdit, /** ProgressToken,*/ Position } from 'vscode-languageserver';\nimport { analyzer } from './analyze';\nimport { codeActionHandlers } from './code-actions/code-action-handler';\nimport { createFixAllAction } from './code-actions/quick-fixes';\nimport { Config, config, EnvVariableTransformers, getDefaultConfiguration, handleEnvOutput } from './config';\nimport { getDiagnosticsAsync } from './diagnostics/validate';\nimport { documents } from './document';\nimport { buildExecuteNotificationResponse, execEntireBuffer, fishLspPromptIcon, useMessageKind } from './execute-handler';\nimport { logger } from './logger';\nimport { env } from './utils/env-manager';\nimport { execAsync, execAsyncF, execAsyncFish } from './utils/exec';\nimport { EnvVariableJson, PrebuiltDocumentationMap } from './utils/snippets';\nimport { pathToUri, uriToPath, uriToReadablePath } from './utils/translation';\nimport { getRange } from './utils/tree-sitter';\nimport { workspaceManager } from './utils/workspace-manager';\nimport { PkgJson } from './utils/commander-cli-subcommands';\nimport FishServer from './server';\nimport { SyncFileHelper } from './utils/file-operations';\n\n// Define command name constants to avoid string literals\nexport const CommandNames = {\n EXECUTE_RANGE: 'fish-lsp.executeRange',\n EXECUTE_LINE: 'fish-lsp.executeLine',\n EXECUTE: 'fish-lsp.execute',\n EXECUTE_BUFFER: 'fish-lsp.executeBuffer',\n CREATE_THEME: 'fish-lsp.createTheme',\n SHOW_STATUS_DOCS: 'fish-lsp.showStatusDocs',\n SHOW_WORKSPACE_MESSAGE: 'fish-lsp.showWorkspaceMessage',\n UPDATE_WORKSPACE: 'fish-lsp.updateWorkspace',\n FIX_ALL: 'fish-lsp.fixAll',\n TOGGLE_SINGLE_WORKSPACE_SUPPORT: 'fish-lsp.toggleSingleWorkspaceSupport',\n GENERATE_ENV_VARIABLES: 'fish-lsp.generateEnvVariables',\n SHOW_ENV_VARIABLES: 'fish-lsp.showEnvVariables',\n CHECK_HEALTH: 'fish-lsp.checkHealth',\n SHOW_REFERENCES: 'fish-lsp.showReferences',\n SHOW_INFO: 'fish-lsp.showInfo',\n} as const;\n\nexport const LspCommands = [...Array.from(Object.values(CommandNames))];\n\nexport type CommandName = typeof CommandNames[keyof typeof CommandNames];\n\n// Type for command arguments\nexport type CommandArgs = {\n // All commands now use variadic string[] with parser functions\n [CommandNames.EXECUTE_RANGE]: string[]; // [path, \"start,end\"] or [path, start, end]\n [CommandNames.EXECUTE_LINE]: string[]; // [path, line]\n [CommandNames.EXECUTE]: string[]; // [path] (alias for EXECUTE_BUFFER)\n [CommandNames.EXECUTE_BUFFER]: string[]; // [path]\n [CommandNames.CREATE_THEME]: string[]; // [path, asVariables?]\n [CommandNames.SHOW_STATUS_DOCS]: [statusCode: string]; // Not converted yet\n [CommandNames.SHOW_WORKSPACE_MESSAGE]: [];\n [CommandNames.UPDATE_WORKSPACE]: string[]; // [path, ...flags]\n [CommandNames.FIX_ALL]: string[]; // [path]\n [CommandNames.TOGGLE_SINGLE_WORKSPACE_SUPPORT]: [];\n [CommandNames.GENERATE_ENV_VARIABLES]: string[]; // [path]\n [CommandNames.SHOW_REFERENCES]: string[]; // [symbolName] or [path, line, char] or [path, \"line,char\"]\n [CommandNames.SHOW_INFO]: [];\n [CommandNames.SHOW_ENV_VARIABLES]: string[]; // [...opts]\n};\n\n// Command help messages for user-facing documentation\nconst CommandHelpMessages = {\n [CommandNames.EXECUTE_RANGE]: {\n usage: [\n 'fish-lsp.executeRange ,',\n 'fish-lsp.executeRange ',\n ],\n examples: [\n 'fish-lsp.executeRange ~/.config/fish/config.fish 1,10',\n 'fish-lsp.executeRange ~/.config/fish/config.fish 1 10',\n 'fish-lsp.executeRange $XDG_CONFIG_HOME/fish/config.fish 5 15',\n ],\n description: 'Execute a range of lines from a Fish script',\n },\n [CommandNames.EXECUTE_LINE]: {\n usage: 'fish-lsp.executeLine ',\n examples: [\n 'fish-lsp.executeLine ~/.config/fish/config.fish 7',\n 'fish-lsp.executeLine /path/to/script.fish 42',\n ],\n description: 'Execute a single line from a Fish script',\n },\n [CommandNames.EXECUTE_BUFFER]: {\n usage: 'fish-lsp.executeBuffer ',\n examples: [\n 'fish-lsp.executeBuffer ~/.config/fish/config.fish',\n ],\n description: 'Execute the entire Fish script buffer',\n },\n [CommandNames.CREATE_THEME]: {\n usage: 'fish-lsp.createTheme [asVariables]',\n examples: [\n 'fish-lsp.createTheme ~/.config/fish/theme.fish',\n 'fish-lsp.createTheme ~/theme.fish true',\n ],\n description: 'Create a Fish theme configuration file',\n },\n [CommandNames.SHOW_STATUS_DOCS]: {\n usage: 'fish-lsp.showStatusDocs ',\n examples: [\n 'fish-lsp.showStatusDocs 0',\n 'fish-lsp.showStatusDocs 127',\n ],\n description: 'Show documentation for a Fish exit status code',\n },\n [CommandNames.FIX_ALL]: {\n usage: 'fish-lsp.fixAll ',\n examples: [\n 'fish-lsp.fixAll ~/.config/fish/config.fish',\n ],\n description: 'Apply all available quick fixes to a Fish script',\n },\n [CommandNames.SHOW_REFERENCES]: {\n usage: [\n 'fish-lsp.showReferences ',\n 'fish-lsp.showReferences ,',\n 'fish-lsp.showReferences ',\n ],\n examples: [\n 'fish-lsp.showReferences my_function',\n 'fish-lsp.showReferences ~/.config/fish/config.fish 7,10',\n 'fish-lsp.showReferences $XDG_CONFIG_HOME/fish/config.fish 7 10',\n 'fish-lsp.showReferences /absolute/path/to/file.fish 7 10',\n ],\n description: 'Find all references to a symbol or location in Fish scripts',\n },\n} as const;\n\n// Helper to format command help message\nfunction formatCommandHelp(commandName: CommandName, reason?: string): string {\n const help = CommandHelpMessages[commandName as keyof typeof CommandHelpMessages];\n if (!help) {\n return `No help available for command: ${commandName}`;\n }\n\n const usageLines = (Array.isArray(help.usage) ? help.usage : [help.usage]) as string[];\n const reasonText = reason ? `Invalid arguments: ${reason}\\n\\n` : '';\n\n return (\n reasonText +\n `${help.description}\\n\\n` +\n 'Usage:\\n' +\n usageLines.map((u: string) => ` ${u}`).join('\\n') +\n '\\n\\nExamples:\\n' +\n help.examples.map((e: string) => ` ${e}`).join('\\n')\n );\n}\n\n// Utility for parsing number arguments (handles string/number inputs and quoted strings)\ntype ParsedNumber =\n | { success: true; value: number; }\n | { success: false; error: string; };\n\nfunction parseNumberArg(value: string | number, argName: string = 'argument'): ParsedNumber {\n if (typeof value === 'number') {\n return { success: true, value };\n }\n\n if (typeof value === 'string') {\n // Remove leading/trailing single or double quotes\n const stripped = value.replace(/^['\"]|['\"]$/g, '');\n const num = parseInt(stripped, 10);\n\n if (isNaN(num)) {\n return { success: false, error: `${argName} must be a number, got: \"${value}\"` };\n }\n\n return { success: true, value: num };\n }\n\n return { success: false, error: `${argName} must be a string or number, got: ${typeof value}` };\n}\n\n/**\n * Converts a 1-indexed line number (user-facing) to 0-indexed (LSP internal).\n * User sees line 7 in editor → LSP uses line 6.\n *\n * @param line - 1-indexed line number from user input\n * @returns 0-indexed line number for LSP operations\n * @example toZeroIndexed(7) // returns 6\n */\nfunction toZeroIndexed(line: number): number {\n return line - 1;\n}\n\n/**\n * Parses and validates a path argument from command arguments.\n * Automatically expands environment variables and tilde.\n *\n * @param args - Array of command arguments\n * @param argIndex - Index of the path argument (default: 0)\n * @returns Parsed path with expansion applied, or error\n *\n * @example\n * parsePathArg(['~/.config/fish/config.fish'])\n * // { success: true, path: '/home/user/.config/fish/config.fish' }\n *\n * parsePathArg(['$HOME/script.fish'])\n * // { success: true, path: '/home/user/script.fish' }\n *\n * parsePathArg([])\n * // { success: false, error: 'Missing path argument' }\n */\ntype ParsedPath =\n | { success: true; path: string; }\n | { success: false; error: string; };\n\nfunction parsePathArg(args: string[], argIndex: number = 0): ParsedPath {\n if (argIndex >= args.length) {\n return { success: false, error: 'Missing path argument' };\n }\n\n const pathArg = args[argIndex];\n if (!pathArg || typeof pathArg !== 'string') {\n return { success: false, error: 'Path must be a string' };\n }\n\n // Expand path immediately (handles ~, $ENV_VARS, etc.)\n const expandedPath = SyncFileHelper.expandEnvVars(pathArg);\n\n return { success: true, path: expandedPath };\n}\n\n/**\n * Parses a pair of numbers from flexible input formats.\n * Supports: \"7,10\" (comma-separated) or \"7\" \"10\" (space-separated)\n *\n * NOTE: This is a reusable utility that can be applied to other commands in the future.\n * Consider refactoring other multi-number parameter commands to use this pattern.\n *\n * @param args - Array of arguments that may contain the number pair\n * @param startIndex - Index in args where the pair starts\n * @param firstName - Name of first number (for error messages)\n * @param secondName - Name of second number (for error messages)\n * @returns Parsed number pair or error\n *\n * @example\n * parseNumberPair(['7,10'], 0, 'start', 'end') // { success: true, first: 7, second: 10 }\n * parseNumberPair(['7', '10'], 0, 'line', 'char') // { success: true, first: 7, second: 10 }\n */\ntype ParsedNumberPair =\n | { success: true; first: number; second: number; }\n | { success: false; error: string; };\n\nfunction parseNumberPair(\n args: (string | number)[],\n startIndex: number,\n firstName: string = 'first',\n secondName: string = 'second',\n): ParsedNumberPair {\n // Case 1: Comma-separated in single argument - \"7,10\"\n if (startIndex < args.length && typeof args[startIndex] === 'string') {\n const arg = args[startIndex] as string;\n if (arg.includes(',')) {\n const parts = arg.split(',');\n if (parts.length !== 2) {\n return { success: false, error: `Expected format: \"${firstName},${secondName}\"` };\n }\n\n const [firstStr, secondStr] = parts;\n if (!firstStr || !secondStr) {\n return { success: false, error: `Missing ${firstName} or ${secondName}` };\n }\n\n const firstResult = parseNumberArg(firstStr, firstName);\n if (!firstResult.success) {\n return { success: false, error: (firstResult as { success: false; error: string; }).error };\n }\n\n const secondResult = parseNumberArg(secondStr, secondName);\n if (!secondResult.success) {\n return { success: false, error: (secondResult as { success: false; error: string; }).error };\n }\n\n return { success: true, first: firstResult.value, second: secondResult.value };\n }\n }\n\n // Case 2: Space-separated in two arguments - \"7\" \"10\"\n if (startIndex + 1 < args.length) {\n const firstArg = args[startIndex];\n const secondArg = args[startIndex + 1];\n\n if (firstArg === undefined || secondArg === undefined) {\n return { success: false, error: `Missing ${firstName} or ${secondName}` };\n }\n const firstResult = parseNumberArg(firstArg, firstName);\n if (!firstResult.success) {\n return { success: false, error: (firstResult as { success: false; error: string; }).error };\n }\n\n const secondResult = parseNumberArg(secondArg, secondName);\n if (!secondResult.success) {\n return { success: false, error: (secondResult as { success: false; error: string; }).error };\n }\n\n return { success: true, first: firstResult.value, second: secondResult.value };\n }\n\n return { success: false, error: `Expected either \"${firstName},${secondName}\" or \"${firstName}\" \"${secondName}\"` };\n}\n\n// Function to create the command handler with dependencies injected\nexport function createExecuteCommandHandler(\n connection: Connection,\n) {\n const showMessage = (message: string, type: MessageType = MessageType.Info) => {\n if (type === MessageType.Info) {\n connection.window.showInformationMessage(message);\n connection.sendNotification('window/showMessage', {\n message: message,\n type: MessageType.Info,\n });\n logger.info(message);\n } else {\n connection.window.showErrorMessage(message);\n connection.sendNotification('window/showMessage', {\n message: message,\n type: MessageType.Error,\n });\n logger.error(message);\n }\n };\n\n // Parse executeRange arguments with flexible position formats\n type ParsedExecuteRangeArgs =\n | { type: 'valid'; path: string; startLine: number; endLine: number; }\n | { type: 'invalid'; reason: string; };\n\n function parseExecuteRangeArgs(args: string[]): ParsedExecuteRangeArgs {\n // Need at least 2 args: path + range\n if (args.length < 2) {\n return { type: 'invalid', reason: 'Missing arguments (need path and line range)' };\n }\n\n const [pathArg, ...restArgs] = args;\n if (!pathArg) {\n return { type: 'invalid', reason: 'Missing path argument' };\n }\n\n // Parse the line range starting from index 0 of restArgs\n const pairResult = parseNumberPair(restArgs, 0, 'startLine', 'endLine');\n\n if (!pairResult.success) {\n return { type: 'invalid', reason: (pairResult as { success: false; error: string; }).error };\n }\n\n // TypeScript now knows pairResult.success is true\n return {\n type: 'valid',\n path: pathArg,\n startLine: pairResult.first,\n endLine: pairResult.second,\n };\n }\n\n async function executeRange(...args: string[]) {\n logger.log('executeRange called with args:', args);\n\n const parsed = parseExecuteRangeArgs(args);\n\n if (parsed.type === 'invalid') {\n logger.warning('Invalid executeRange arguments:', { args, reason: parsed.reason });\n showMessage(\n formatCommandHelp(CommandNames.EXECUTE_RANGE, parsed.reason),\n MessageType.Error,\n );\n return;\n }\n\n let { path } = parsed;\n const { startLine, endLine } = parsed; // Lines are 1-indexed from user\n\n // Expand path (handles ~, $ENV_VARS, etc.)\n path = SyncFileHelper.expandEnvVars(path);\n\n // could also do executeLine() on every line in the range\n const cached = analyzer.analyzePath(path);\n if (!cached) {\n showMessage(`File not found or could not be analyzed: ${path}`, MessageType.Error);\n return;\n }\n const { document } = cached;\n const current = document;\n if (!current) return;\n const start = current.getLineStart(toZeroIndexed(startLine));\n const end = current.getLineEnd(toZeroIndexed(endLine));\n const range = Range.create(start.line, start.character, end.line, end.character);\n logger.log('executeRange', current.uri, range);\n\n const text = current.getText(range);\n const output = (await execAsync(text)).stdout || '';\n\n logger.log('onExecuteCommand', text);\n logger.log('onExecuteCommand', output);\n const response = buildExecuteNotificationResponse(text.split('\\n').map(s => s.replace(/;\\s?$/, '')).join('; '), { stdout: '\\n' + output, stderr: '' });\n useMessageKind(connection, response);\n }\n\n // Parse executeLine arguments\n type ParsedExecuteLineArgs =\n | { type: 'valid'; path: string; line: number; }\n | { type: 'invalid'; reason: string; };\n\n function parseExecuteLineArgs(args: string[]): ParsedExecuteLineArgs {\n // Parse path (index 0)\n const pathResult = parsePathArg(args, 0);\n\n if (!pathResult.success) {\n return { type: 'invalid', reason: (pathResult as { success: false; error: string; }).error };\n }\n\n // Parse line number (index 1)\n if (args.length < 2) {\n return { type: 'invalid', reason: 'Missing line number argument' };\n }\n const line = args[1];\n if (!line) {\n return { type: 'invalid', reason: 'Line number must be provided' };\n }\n\n const lineResult = parseNumberArg(line, 'line');\n if (!lineResult.success) {\n return { type: 'invalid', reason: (lineResult as { success: false; error: string; }).error };\n }\n\n return { type: 'valid', path: pathResult.path, line: lineResult.value };\n }\n\n async function executeLine(...args: string[]) {\n logger.log('executeLine called with args:', args);\n\n const parsed = parseExecuteLineArgs(args);\n\n if (parsed.type === 'invalid') {\n logger.warning('Invalid executeLine arguments:', { args, reason: parsed.reason });\n showMessage(\n formatCommandHelp(CommandNames.EXECUTE_LINE, parsed.reason),\n MessageType.Error,\n );\n return;\n }\n\n const { path, line: lineNumber } = parsed; // Path already expanded by parsePathArg\n\n const cached = analyzer.analyzePath(path);\n if (!cached) {\n showMessage(`File not found or could not be analyzed: ${path}`, MessageType.Error);\n return;\n }\n const { document } = cached;\n logger.log('executeLine', document.uri, lineNumber);\n if (!document) return;\n\n const zeroIndexedLine = toZeroIndexed(lineNumber);\n\n const text = document.getLine(zeroIndexedLine);\n const cmdOutput = await execAsyncF(`${text}; echo \"\\\\$status: $status\"`);\n logger.log('executeLine.cmdOutput', cmdOutput);\n const output = buildExecuteNotificationResponse(text, { stdout: cmdOutput, stderr: '' });\n\n logger.log('onExecuteCommand', text);\n logger.log('onExecuteCommand', output);\n // const response = buildExecuteNotificationResponse(text, );\n useMessageKind(connection, output);\n }\n\n // Parse createTheme arguments\n type ParsedCreateThemeArgs =\n | { type: 'valid'; path: string; asVariables: boolean; }\n | { type: 'invalid'; reason: string; };\n\n function parseCreateThemeArgs(args: string[]): ParsedCreateThemeArgs {\n const pathResult = parsePathArg(args, 0);\n\n if (!pathResult.success) {\n return { type: 'invalid', reason: (pathResult as { success: false; error: string; }).error };\n }\n\n // Optional second argument for asVariables (default: true)\n let asVariables = true;\n if (args.length >= 2) {\n const asVarArg = args[1];\n // Accept various boolean representations (all args are strings from LSP)\n if (asVarArg === 'false' || asVarArg === '0') {\n asVariables = false;\n }\n }\n\n return { type: 'valid', path: pathResult.path, asVariables };\n }\n\n async function createTheme(...args: string[]) {\n logger.log('createTheme called with args:', args);\n\n const parsed = parseCreateThemeArgs(args);\n\n if (parsed.type === 'invalid') {\n logger.warning('Invalid createTheme arguments:', { args, reason: parsed.reason });\n showMessage(\n formatCommandHelp(CommandNames.CREATE_THEME, parsed.reason),\n MessageType.Error,\n );\n return;\n }\n\n const { path, asVariables } = parsed; // Path already expanded by parsePathArg\n\n const cached = analyzer.analyzePath(path);\n if (!cached) return;\n const { document } = cached;\n const output = (await execAsyncFish('fish_config theme dump; or true')).stdout.split('\\n');\n\n if (!document) {\n logger.error('createTheme', 'Document not found');\n connection.sendNotification('window/showMessage', {\n message: ` Document not found: ${uriToReadablePath(pathToUri(path))} `,\n type: MessageType.Error,\n });\n return;\n }\n const outputArr: string[] = [];\n // Append the longest line to the file\n if (asVariables) {\n outputArr.push('\\n\\n# created by fish-lsp');\n }\n for (const line of output) {\n if (asVariables) {\n outputArr.push(`set -gx ${line}`);\n } else {\n outputArr.push(`${line}`);\n }\n }\n const outputStr = outputArr.join('\\n');\n const docsEnd = document.positionAt(document.getLines());\n const workspaceEdit: WorkspaceEdit = {\n changes: {\n [document.uri]: [\n TextEdit.insert(docsEnd, outputStr),\n ],\n },\n };\n await connection.workspace.applyEdit(workspaceEdit);\n await connection.sendRequest('window/showDocument', {\n uri: document.uri,\n takeFocus: true,\n });\n\n useMessageKind(connection, {\n message: `${fishLspPromptIcon} appended theme variables to end of file`,\n kind: 'info',\n });\n }\n\n // Parse executeBuffer arguments\n type ParsedExecuteBufferArgs =\n | { type: 'valid'; path: string; }\n | { type: 'invalid'; reason: string; };\n\n function parseExecuteBufferArgs(args: string[]): ParsedExecuteBufferArgs {\n const pathResult = parsePathArg(args, 0);\n\n if (!pathResult.success) {\n return { type: 'invalid', reason: (pathResult as { success: false; error: string; }).error };\n }\n\n return { type: 'valid', path: pathResult.path };\n }\n\n async function executeBuffer(...args: string[]) {\n logger.log('executeBuffer called with args:', args);\n\n const parsed = parseExecuteBufferArgs(args);\n\n if (parsed.type === 'invalid') {\n logger.warning('Invalid executeBuffer arguments:', { args, reason: parsed.reason });\n showMessage(\n formatCommandHelp(CommandNames.EXECUTE_BUFFER, parsed.reason),\n MessageType.Error,\n );\n return;\n }\n\n const { path } = parsed; // Path already expanded by parsePathArg\n\n const output = await execEntireBuffer(path);\n // Append the longest line to the file\n useMessageKind(connection, output);\n }\n\n function handleShowStatusDocs(statusCode?: string | number) {\n if (!statusCode) {\n logger.log('handleShowStatusDocs', 'No status code provided');\n showMessage('No status code provided', MessageType.Error);\n return;\n }\n if (typeof statusCode === 'string' && statusCode.startsWith(\"'\") && statusCode.endsWith(\"'\")) {\n statusCode = statusCode.slice(1, -1).toString();\n logger.log('handleShowStatusDocs', 'statusCode is string', statusCode);\n }\n statusCode = Number.parseInt(statusCode.toString()).toString();\n const statusInfo = PrebuiltDocumentationMap.getByType('status')\n .find(item => item.name === statusCode);\n\n logger.log('handleShowStatusDocs', statusCode, {\n foundStatusInfo: PrebuiltDocumentationMap.getByType('status').map(item => item.name),\n statusParam: statusCode,\n statusInfoFound: statusInfo,\n });\n\n if (statusInfo) {\n let docMessage = `Status Code: ${statusInfo.name}\\n\\n`;\n const description = statusInfo.description.split(' ');\n let lineLen = 0;\n for (let i = 0; i < description.length; i++) {\n const word = description[i];\n if (!word) continue;\n if (lineLen + word?.length > 80) {\n docMessage += '\\n' + word;\n lineLen = 0;\n continue;\n } else if (lineLen === 0) {\n docMessage += word;\n lineLen += word.length;\n } else {\n docMessage += ' ' + word;\n lineLen += word.length + 1;\n }\n }\n showMessage(docMessage, MessageType.Info);\n } else {\n showMessage(`No documentation found for status code: ${statusCode}`, MessageType.Error);\n }\n }\n\n function showWorkspaceMessage() {\n const message = `${fishLspPromptIcon} Workspace: ${workspaceManager.current?.name}\\n\\n Total files analyzed: ${workspaceManager.current?.uris.indexedCount}`;\n logger.log('showWorkspaceMessage',\n config,\n );\n showMessage(message, MessageType.Info);\n return undefined;\n }\n\n // Parse _updateWorkspace arguments\n type ParsedUpdateWorkspaceArgs =\n | { type: 'valid'; path: string; flags: string[]; }\n | { type: 'invalid'; reason: string; };\n\n function parseUpdateWorkspaceArgs(args: string[]): ParsedUpdateWorkspaceArgs {\n const pathResult = parsePathArg(args, 0);\n\n if (!pathResult.success) {\n return { type: 'invalid', reason: (pathResult as { success: false; error: string; }).error };\n }\n\n // Remaining args are flags\n const flags = args.slice(1);\n\n return { type: 'valid', path: pathResult.path, flags };\n }\n\n async function _updateWorkspace(...args: string[]) {\n logger.log('_updateWorkspace called with args:', args);\n\n const parsed = parseUpdateWorkspaceArgs(args);\n\n if (parsed.type === 'invalid') {\n logger.warning('Invalid _updateWorkspace arguments:', { args, reason: parsed.reason });\n showMessage(\n formatCommandHelp(CommandNames.UPDATE_WORKSPACE, parsed.reason),\n MessageType.Error,\n );\n return;\n }\n\n const { path, flags } = parsed; // Path already expanded by parsePathArg\n const silence = flags.includes('--quiet') || flags.includes('-q');\n\n const uri = pathToUri(path);\n workspaceManager.handleUpdateDocument(uri);\n const message = `${fishLspPromptIcon} Workspace: ${workspaceManager.current?.path}`;\n connection.sendNotification('workspace/didChangeWorkspaceFolders', {\n event: {\n added: [path],\n removed: [],\n },\n });\n\n if (silence) return undefined;\n\n // Using the notification method directly\n showMessage(message, MessageType.Info);\n return undefined;\n }\n\n // Parse fixAllDiagnostics arguments\n type ParsedFixAllDiagnosticsArgs =\n | { type: 'valid'; path: string; }\n | { type: 'invalid'; reason: string; };\n\n function parseFixAllDiagnosticsArgs(args: string[]): ParsedFixAllDiagnosticsArgs {\n const pathResult = parsePathArg(args, 0);\n\n if (!pathResult.success) {\n return { type: 'invalid', reason: (pathResult as { success: false; error: string; }).error };\n }\n\n return { type: 'valid', path: pathResult.path };\n }\n\n async function fixAllDiagnostics(...args: string[]) {\n logger.log('fixAllDiagnostics called with args:', args);\n\n const parsed = parseFixAllDiagnosticsArgs(args);\n\n if (parsed.type === 'invalid') {\n logger.warning('Invalid fixAllDiagnostics arguments:', { args, reason: parsed.reason });\n showMessage(\n formatCommandHelp(CommandNames.FIX_ALL, parsed.reason),\n MessageType.Error,\n );\n return;\n }\n\n const { path } = parsed; // Path already expanded by parsePathArg\n\n const uri = pathToUri(path);\n logger.log('fixAllDiagnostics', uri);\n const cached = analyzer.analyzePath(path);\n if (!cached) {\n showMessage(`File not found or could not be analyzed: ${path}`, MessageType.Error);\n return;\n }\n const { document } = cached;\n const root = analyzer.getRootNode(uri);\n if (!document || !root) return;\n const diagnostics = root ? await getDiagnosticsAsync(root, document) : [];\n\n logger.warning('fixAllDiagnostics', diagnostics.length, 'diagnostics found');\n if (diagnostics.length === 0) {\n logger.log('No diagnostics found');\n return;\n }\n\n const { onCodeActionCallback } = codeActionHandlers();\n\n const actions = await onCodeActionCallback({\n textDocument: document.asTextDocumentIdentifier(),\n range: getRange(root),\n context: {\n diagnostics: diagnostics,\n },\n });\n logger.log('fixAllDiagnostics', actions);\n const fixAllAction = createFixAllAction(document, actions);\n if (!fixAllAction) {\n logger.log('fixAllDiagnostics did not find any fixAll actions');\n return;\n }\n const fixCount = fixAllAction?.data.totalEdits || 0;\n if (fixCount > 0) {\n logger.log('fixAllDiagnostics', `Can apply ${fixCount} fixes`);\n const result = await connection.window.showInformationMessage(\n `Fix all ${fixAllAction.data.totalEdits} diagnostics on ${uriToReadablePath(uri)}`,\n { title: 'Yes' },\n { title: 'Cancel' },\n );\n const { title } = result?.title ? result : { title: 'Cancel' };\n if (title === 'Cancel') {\n connection.sendNotification('window/showMessage', {\n type: MessageType.Info, // Info, Warning, Error, Log\n message: ' No changes were made to the file. ',\n });\n return;\n }\n // Apply all edits\n const workspaceEdit = fixAllAction.edit;\n if (!workspaceEdit) return;\n await connection.workspace.applyEdit(workspaceEdit);\n connection.sendNotification('window/showMessage', {\n type: MessageType.Info, // Info, Warning, Error, Log\n message: ` Applied ${fixCount} quick fixes `,\n });\n }\n }\n\n function toggleSingleWorkspaceSupport() {\n const currentConfig = config.fish_lsp_single_workspace_support;\n config.fish_lsp_single_workspace_support = !currentConfig;\n connection.sendNotification('window/showMessage', {\n type: MessageType.Info, // Info, Warning, Error, Log\n message: ` Single workspace support: ${config.fish_lsp_single_workspace_support ? 'ENABLED' : 'DISABLED'} `,\n });\n }\n\n // Parse outputFishLspEnv arguments\n type ParsedOutputFishLspEnvArgs =\n | { type: 'valid'; path: string; }\n | { type: 'invalid'; reason: string; };\n\n function parseOutputFishLspEnvArgs(args: string[]): ParsedOutputFishLspEnvArgs {\n const pathResult = parsePathArg(args, 0);\n\n if (!pathResult.success) {\n return { type: 'invalid', reason: (pathResult as { success: false; error: string; }).error };\n }\n\n return { type: 'valid', path: pathResult.path };\n }\n\n const envOutputOptions = {\n confd: false,\n comments: true,\n global: true,\n local: false,\n export: true,\n json: false,\n only: undefined,\n };\n\n function outputFishLspEnv(...args: string[]) {\n logger.log('outputFishLspEnv called with args:', args);\n\n const parsed = parseOutputFishLspEnvArgs(args);\n\n if (parsed.type === 'invalid') {\n logger.warning('Invalid outputFishLspEnv arguments:', { args, reason: parsed.reason });\n showMessage(\n formatCommandHelp(CommandNames.GENERATE_ENV_VARIABLES, parsed.reason),\n MessageType.Error,\n );\n return;\n }\n\n const { path } = parsed; // Path already expanded by parsePathArg\n const cached = analyzer.analyzePath(path);\n if (!cached) return;\n const { document } = cached;\n if (!document) return;\n const output: string[] = ['\\n'];\n const outputCallback = (s: string) => {\n output.push(s);\n };\n handleEnvOutput('show', outputCallback, envOutputOptions);\n showMessage(`${fishLspPromptIcon} Appending fish-lsp environment variables to the end of the file`, MessageType.Info);\n const docsEnd = document.positionAt(document.getLines());\n const workspaceEdit: WorkspaceEdit = {\n changes: {\n [document.uri]: [\n TextEdit.insert(docsEnd, output.join('\\n')),\n ],\n },\n };\n connection.workspace.applyEdit(workspaceEdit);\n }\n\n type ParsedShowReferencesArgs =\n | { type: 'symbol'; name: string; }\n | { type: 'location'; path: string; line: number; char: number; }\n | { type: 'invalid'; reason: string; };\n\n function parseShowReferencesArgs(args: string[]): ParsedShowReferencesArgs {\n // Case 1: Single argument - could be symbol name only\n if (args.length === 1) {\n const [arg] = args;\n if (!arg) {\n return { type: 'invalid', reason: 'Missing argument' };\n }\n // Check if this looks like a path (contains /, ~, or $ENV_VAR)\n // OR if it can be expanded to a different value (meaning it has expandable components)\n const isPathLike = arg.includes('/') || arg.startsWith('~') || arg.includes('$');\n const canExpand = SyncFileHelper.isExpandable(arg);\n\n if (isPathLike || canExpand) {\n return { type: 'invalid', reason: 'Path provided without line/character position' };\n }\n return { type: 'symbol', name: arg };\n }\n\n // Case 2 & 3: Path with position - use parseNumberPair for flexibility\n if (args.length >= 2) {\n const [pathArg, ...positionArgs] = args;\n if (!pathArg) {\n return { type: 'invalid', reason: 'Missing path argument' };\n }\n\n // Use the generic parseNumberPair utility to handle both \"line,char\" and \"line\" \"char\"\n const pairResult = parseNumberPair(positionArgs, 0, 'line', 'character');\n\n if (!pairResult.success) {\n return { type: 'invalid', reason: (pairResult as { success: false; error: string; }).error };\n }\n\n // TypeScript now knows pairResult.success is true\n return {\n type: 'location',\n path: pathArg,\n line: pairResult.first,\n char: pairResult.second,\n };\n }\n\n return { type: 'invalid', reason: 'No arguments provided' };\n }\n\n async function showReferences(...args: string[]) {\n logger.log('showReferences called with args:', args);\n\n const parsed = parseShowReferencesArgs(args);\n\n if (parsed.type === 'invalid') {\n logger.warning('Invalid showReferences arguments:', { args, reason: parsed.reason });\n showMessage(\n formatCommandHelp(CommandNames.SHOW_REFERENCES, parsed.reason),\n MessageType.Error,\n );\n return [];\n }\n\n let uri: string;\n let position: Position;\n\n if (parsed.type === 'symbol') {\n logger.log('Searching for global symbol:', parsed.name);\n\n const globalSymbol = analyzer.globalSymbols.findFirst(parsed.name);\n\n if (!globalSymbol) {\n showMessage(`No global symbol found with name: ${parsed.name}`, MessageType.Error);\n return [];\n }\n\n logger.log('Found global symbol:', {\n name: globalSymbol.name,\n uri: globalSymbol.uri,\n range: globalSymbol.range,\n });\n\n uri = globalSymbol.uri;\n position = globalSymbol.toPosition();\n } else if (parsed.type === 'location') {\n // Use SyncFileHelper to properly expand path (handles ~, $ENV_VARS, etc.)\n const expandedPath = SyncFileHelper.expandEnvVars(parsed.path);\n\n // Numbers are already parsed and validated by parseShowReferencesArgs\n // Convert 1-indexed (user-facing) line numbers to 0-indexed (LSP) positions\n uri = pathToUri(expandedPath);\n position = Position.create(toZeroIndexed(parsed.line), parsed.char);\n } else {\n return [];\n }\n\n logger.log('showReferences', { uri, position });\n\n // Call server.onReferences() directly to get references\n const references = await FishServer.instance.onReferences({\n textDocument: { uri },\n position: position,\n context: {\n includeDeclaration: true,\n },\n });\n\n logger.log('showReferences result', {\n count: references.length,\n references: references.map(loc => ({\n uri: loc.uri,\n range: loc.range,\n })),\n });\n\n if (references.length === 0) {\n showMessage(\n `No references found at ${uriToReadablePath(uri)}:${position.line + 1}:${position.character + 1}`,\n MessageType.Info,\n );\n return references;\n } else {\n // Format references as a readable message\n const refMessage = references.map((loc, idx) => {\n const locPath = uriToReadablePath(loc.uri);\n const line = loc.range.start.line + 1;\n const char = loc.range.start.character + 1;\n return ` [${idx + 1}] ${locPath}:${line}:${char}`;\n }).join('\\n');\n\n const message = `Found ${references.length} reference(s):\\n${refMessage}`;\n showMessage(message, MessageType.Info);\n }\n\n // Group references by URI to find the first reference in each document\n const referencesByUri = new Map();\n for (const ref of references) {\n const existing = referencesByUri.get(ref.uri) || [];\n existing.push(ref);\n referencesByUri.set(ref.uri, existing);\n }\n\n // Navigate to the first reference in each document\n for (const [refUri, refs] of referencesByUri.entries()) {\n // Ensure document is un-opened\n if (documents.get(uriToPath(refUri)) || uri === refUri) {\n logger.log(`Document already open, skipping: ${uriToReadablePath(refUri)}`);\n continue;\n }\n\n // Verify the document exists before trying to open it\n const refPath = uriToPath(refUri);\n const refDoc = documents.get(refPath) || analyzer.analyzePath(refPath)?.document;\n\n if (!refDoc) {\n logger.warning(`Skipping non-existent document: ${uriToReadablePath(refUri)}`);\n continue;\n }\n\n // Sort references by line number to get the first one in the document\n const sortedRefs = refs.sort((a, b) => {\n if (a.range.start.line !== b.range.start.line) {\n return a.range.start.line - b.range.start.line;\n }\n return a.range.start.character - b.range.start.character;\n });\n\n const firstRef = sortedRefs[0];\n if (!firstRef) continue;\n\n if (workspaceManager.current?.getUris().includes(refUri) === false) {\n logger.log(`Reference URI not in current workspace, skipping: ${uriToReadablePath(refUri)}`);\n continue;\n }\n\n // Use window/showDocument to open and navigate to the first reference\n try {\n await connection.sendRequest('window/showDocument', {\n uri: refUri,\n takeFocus: false, // Don't steal focus from current document\n selection: firstRef?.range, // Highlight the first reference\n });\n logger.log(`Opened ${uriToReadablePath(refUri)} at line ${firstRef!.range.start.line + 1}`);\n } catch (error) {\n logger.error(`Failed to show document ${refUri}:`, error);\n }\n }\n\n return references;\n }\n\n function showEnvVariables(...opts: string[]) {\n if (!opts.some(o => ['all', 'changed', 'default', 'unchanged'].includes(o))) {\n opts = ['all', ...opts];\n }\n const mode = opts[0] || 'all';\n const noComments: boolean = opts.find(o => o === '--no-comments') ? true : false;\n const noValues: boolean = opts.find(o => o === '--no-values') ? true : false;\n const asJson: boolean = opts.find(o => o === '--json') ? true : false;\n\n let variables = PrebuiltDocumentationMap\n .getByType('variable', 'fishlsp')\n .filter((v) => EnvVariableJson.is(v) ? !v.isDeprecated : false)\n .map(v => v as EnvVariableJson);\n\n const allVars = variables;\n const changedVars = variables.filter(v => env.has(v.name));\n const unchangedVars = allVars.filter(v => !changedVars.map(c => c.name).includes(v.name));\n const defaultVars = variables.filter(v => {\n const defConfig = getDefaultConfiguration();\n return v.name in defConfig;\n });\n\n const defaultConfig = getDefaultConfiguration();\n\n let resVars: EnvVariableJson[] = [];\n if (mode === 'all') {\n resVars = allVars;\n } else if (mode === 'changed') {\n resVars = variables.filter(v => env.has(v.name));\n } else if (mode === 'unchanged') {\n resVars = variables.filter(v => !changedVars.map(c => c.name).includes(v.name));\n } else if (mode === 'default') {\n variables = Object.entries(getDefaultConfiguration()).map(([key, _]) => {\n const EnvVar = variables.find(v => v.name === key);\n if (EnvVar) return EnvVar;\n }).filter((v): v is EnvVariableJson => v !== undefined);\n resVars = variables.filter((v): v is EnvVariableJson => v !== undefined);\n }\n\n const logArr = (resVars: EnvVariableJson[]) => ({\n names: resVars.map(v => v.name),\n len: resVars.length,\n });\n\n logger.log('showEnvVariables', {\n totalVariables: variables.length,\n all: logArr(allVars),\n changedVariables: logArr(changedVars),\n unchangedVariables: logArr(unchangedVars),\n defaultVariables: logArr(defaultVars),\n });\n\n if (asJson) {\n const results: Record = {} as Record;\n resVars.forEach(v => {\n const { name } = v as { name: Config.ConfigKeyType; };\n if (!name || !(name in config)) return;\n if (mode === 'default') results[name] = defaultConfig[name];\n else results[name] = config[name];\n });\n showMessage(\n [\n '\\n{',\n Object.entries(results).map(([key, value]) => {\n const k = JSON.stringify(key);\n const v = JSON.stringify(value).replaceAll('\\n', ' ').trim() + ',';\n return ` ${k}: ${v}`;\n }).join('\\n'),\n '}',\n ].join('\\n'),\n MessageType.Info,\n );\n return;\n }\n\n const filteredAllVars = (vals: EnvVariableJson[]) => {\n const res = vals.map(v => {\n const value = noValues ? '' : EnvVariableTransformers.convertValueToShellOutput(config[v.name as Config.ConfigKeyType]);\n const comment = noComments ? '' : `# ${v.description.replace(/\\n/g, ' ')}\\n`;\n if (noValues && noComments) return `${v.name}`;\n return `${comment}set ${v.name} ${value}\\n`;\n });\n return res.join('\\n');\n };\n\n let message = '\\n';\n if (mode === 'all' || !mode) {\n message += filteredAllVars(allVars);\n } else if (mode === 'changed') {\n message += filteredAllVars(changedVars);\n } else if (mode === 'unchanged') {\n message += filteredAllVars(unchangedVars);\n } else if (mode === 'default') {\n message += filteredAllVars(defaultVars);\n }\n\n showMessage(message.trimEnd(), MessageType.Info);\n }\n\n function showInfo() {\n const message = JSON.stringify({\n version: PkgJson.version,\n buildTime: PkgJson.buildTime,\n repo: PkgJson.path,\n }, null, 2);\n showMessage(message, MessageType.Info);\n }\n\n // Command handler mapping\n const commandHandlers: Record Promise | void | Promise | Promise> = {\n [CommandNames.EXECUTE_RANGE]: executeRange,\n [CommandNames.EXECUTE_LINE]: executeLine,\n [CommandNames.EXECUTE_BUFFER]: executeBuffer,\n [CommandNames.EXECUTE]: executeBuffer,\n [CommandNames.CREATE_THEME]: createTheme,\n [CommandNames.SHOW_STATUS_DOCS]: handleShowStatusDocs,\n [CommandNames.SHOW_WORKSPACE_MESSAGE]: showWorkspaceMessage,\n [CommandNames.UPDATE_WORKSPACE]: _updateWorkspace,\n [CommandNames.FIX_ALL]: fixAllDiagnostics,\n [CommandNames.TOGGLE_SINGLE_WORKSPACE_SUPPORT]: toggleSingleWorkspaceSupport,\n [CommandNames.GENERATE_ENV_VARIABLES]: outputFishLspEnv,\n [CommandNames.SHOW_ENV_VARIABLES]: showEnvVariables,\n [CommandNames.SHOW_REFERENCES]: showReferences,\n [CommandNames.SHOW_INFO]: showInfo,\n };\n\n // Main command handler function\n return async function onExecuteCommand(params: ExecuteCommandParams): Promise {\n logger.log('onExecuteCommand', params);\n\n const handler = commandHandlers[params.command];\n if (!handler) {\n logger.log(`Unknown command: ${params.command}`);\n return;\n }\n\n await handler(...params.arguments || []);\n };\n}\n"
},
{
"path": "src/config.ts",
"content": "import { z } from 'zod';\nimport { Connection, FormattingOptions, InitializeParams, InitializeResult, TextDocumentSyncKind } from 'vscode-languageserver';\nimport { createServerLogger, logger } from './logger';\nimport { PrebuiltDocumentationMap, EnvVariableJson } from './utils/snippets';\nimport { AllSupportedActions } from './code-actions/action-kinds';\nimport { LspCommands } from './command';\nimport { getBuildTimeJsonObj, PackageVersion, SubcommandEnv } from './utils/commander-cli-subcommands';\nimport { ErrorCodes } from './diagnostics/error-codes';\nimport { FishSemanticTokens } from './utils/semantics';\nimport { getProjectRootPath } from './utils/path-resolution';\n\n/********************************************\n ********** Handlers/Providers ***********\n *******************************************/\n\nexport const ConfigHandlerSchema = z.object({\n complete: z.boolean().default(true),\n hover: z.boolean().default(true),\n rename: z.boolean().default(true),\n definition: z.boolean().default(true),\n implementation: z.boolean().default(true),\n reference: z.boolean().default(true),\n logger: z.boolean().default(true),\n formatting: z.boolean().default(true),\n formatRange: z.boolean().default(true),\n typeFormatting: z.boolean().default(true),\n codeAction: z.boolean().default(true),\n codeLens: z.boolean().default(true),\n folding: z.boolean().default(true),\n selectionRange: z.boolean().default(true),\n signature: z.boolean().default(true),\n executeCommand: z.boolean().default(true),\n inlayHint: z.boolean().default(true),\n highlight: z.boolean().default(true),\n diagnostic: z.boolean().default(true),\n popups: z.boolean().default(true),\n semanticTokens: z.boolean().default(true),\n});\n\n/**\n * The configHandlers object stores the enabled/disabled state of the cli flags\n * for the language server handlers.\n *\n * The object (shaped by `ConfigHandlerSchema`) contains a single key and value pair\n * for each handler type that is supported by the language server. Each handler\n * can only either be enabled or disabled, and their default value is `true`.\n *\n * The object could be checked three different times during the initialization of the\n * language server:\n *\n * 1.) The `initializeParams` are passed into the language server during startup\n * - `initializeParams.fish_lsp_enabled_handlers`\n * - `initializeParams.fish_lsp_disabled_handlers`\n\n * 2.) This object parses the shell env values found in the variables:\n * - `fish_lsp_enabled_handlers`\n * - `fish_lsp_disabled_handlers`\n *\n * 3.) Next, it uses the cli flags parsed from the `--enable` and `--disable` flags:\n * - keys are from the validHandlers array.\n *\n * Finally, its values can be used to determine if a handler is enabled or disabled.\n *\n * For example, `configHandlers.complete` will store the state of the `complete` handler.\n */\nexport const configHandlers = ConfigHandlerSchema.parse({});\n\nexport const validHandlers: Array = [\n 'complete', 'hover', 'rename', 'definition', 'implementation', 'reference', 'formatting',\n 'formatRange', 'typeFormatting', 'codeAction', 'codeLens', 'folding', 'signature',\n 'executeCommand', 'inlayHint', 'highlight', 'diagnostic', 'popups', 'semanticTokens',\n];\n\nexport function updateHandlers(keys: string[], value: boolean): void {\n keys.forEach(key => {\n if (validHandlers.includes(key as keyof typeof ConfigHandlerSchema.shape)) {\n configHandlers[key as keyof typeof ConfigHandlerSchema.shape] = value;\n }\n });\n Config.fixEnabledDisabledHandlers();\n}\n\n/********************************************\n ********** User Env ***********\n *******************************************/\n\nexport const ConfigSchema = z.object({\n /** Handlers that are enabled in the language server */\n fish_lsp_enabled_handlers: z.array(z.string()).default([]),\n\n /** Handlers that are disabled in the language server */\n fish_lsp_disabled_handlers: z.array(z.string()).default([]),\n\n /** Characters that completion items will be accepted on */\n fish_lsp_commit_characters: z.array(z.string()).default(['\\t', ';', ' ']),\n\n /** Path to the log files */\n fish_lsp_log_file: z.string().default(''),\n\n /** show startup analysis notification */\n fish_lsp_log_level: z.string().default(''),\n\n /** All workspaces/paths for the language-server to index */\n fish_lsp_all_indexed_paths: z.array(z.string()).default(['$__fish_config_dir', '$__fish_data_dir']),\n\n /** All workspace/paths that the language-server should be able to rename inside*/\n fish_lsp_modifiable_paths: z.array(z.string()).default(['$__fish_config_dir']),\n\n /** error code numbers to disable */\n fish_lsp_diagnostic_disable_error_codes: z.array(z.number()).default([]),\n\n /** max number of diagnostics */\n fish_lsp_max_diagnostics: z.number().default(0),\n\n /** fish lsp experimental diagnostics */\n fish_lsp_enable_experimental_diagnostics: z.boolean().default(false),\n\n /** diagnostic 3002 warnings should be shown forcing the user to check if a command exists before using it */\n fish_lsp_strict_conditional_command_warnings: z.boolean().default(false),\n\n /**\n * include diagnostic warnings when an external shell command is used instead of\n * a fish built-in command\n */\n fish_lsp_prefer_builtin_fish_commands: z.boolean().default(false),\n\n /**\n * don't warn usage of fish wrapper functions\n */\n fish_lsp_allow_fish_wrapper_functions: z.boolean().default(true),\n\n /**\n * require autoloaded functions to have a description in their header\n */\n fish_lsp_require_autoloaded_functions_to_have_description: z.boolean().default(true),\n\n /** max background files */\n fish_lsp_max_background_files: z.number().default(10000),\n\n /** show startup analysis notification */\n fish_lsp_show_client_popups: z.boolean().default(true),\n\n /** single workspace support */\n fish_lsp_single_workspace_support: z.boolean().default(false),\n\n /** paths to ignore when searching for workspace folders */\n fish_lsp_ignore_paths: z.array(z.string()).default(['**/.git/**', '**/node_modules/**', '**/containerized/**', '**/docker/**']),\n\n /** max depth to search for workspace folders */\n fish_lsp_max_workspace_depth: z.number().default(3),\n\n /** path to fish executable for child processes */\n fish_lsp_fish_path: z.string().default('fish'),\n});\n\nexport type Config = z.infer;\n\nexport function getConfigFromEnvironmentVariables(): {\n config: Config;\n environmentVariablesUsed: string[];\n} {\n const rawConfig = {\n fish_lsp_enabled_handlers: process.env.fish_lsp_enabled_handlers?.split(' '),\n fish_lsp_disabled_handlers: process.env.fish_lsp_disabled_handlers?.split(' '),\n fish_lsp_commit_characters: process.env.fish_lsp_commit_characters?.split(' '),\n fish_lsp_log_file: process.env.fish_lsp_log_file || process.env.fish_lsp_logfile,\n fish_lsp_log_level: process.env.fish_lsp_log_level,\n fish_lsp_all_indexed_paths: process.env.fish_lsp_all_indexed_paths?.split(' '),\n fish_lsp_modifiable_paths: process.env.fish_lsp_modifiable_paths?.split(' '),\n fish_lsp_diagnostic_disable_error_codes: process.env.fish_lsp_diagnostic_disable_error_codes?.split(' ').map(toNumber).filter(n => !!n),\n fish_lsp_max_diagnostics: toNumber(process.env.fish_lsp_max_diagnostics || '10'),\n fish_lsp_enable_experimental_diagnostics: toBoolean(process.env.fish_lsp_enable_experimental_diagnostics),\n fish_lsp_prefer_builtin_fish_commands: toBoolean(process.env.fish_lsp_prefer_builtin_fish_commands),\n fish_lsp_strict_conditional_command_warnings: toBoolean(process.env.fish_lsp_strict_conditional_command_warnings),\n fish_lsp_allow_fish_wrapper_functions: toBoolean(process.env.fish_lsp_allow_fish_wrapper_functions),\n fish_lsp_require_autoloaded_functions_to_have_description: toBoolean(process.env.fish_lsp_require_autoloaded_functions_to_have_description),\n fish_lsp_max_background_files: toNumber(process.env.fish_lsp_max_background_files || '10000'),\n fish_lsp_show_client_popups: toBoolean(process.env.fish_lsp_show_client_popups),\n fish_lsp_single_workspace_support: toBoolean(process.env.fish_lsp_single_workspace_support),\n fish_lsp_ignore_paths: process.env.fish_lsp_ignore_paths?.split(' '),\n fish_lsp_max_workspace_depth: toNumber(process.env.fish_lsp_max_workspace_depth || '4'),\n fish_lsp_fish_path: process.env.fish_lsp_fish_path,\n };\n\n const environmentVariablesUsed = Object.entries(rawConfig)\n .map(([key, value]) => typeof value !== 'undefined' ? key : null)\n .filter((key): key is string => key !== null);\n\n const config = ConfigSchema.parse(rawConfig);\n\n if (config.fish_lsp_allow_fish_wrapper_functions) {\n config.fish_lsp_diagnostic_disable_error_codes.push(ErrorCodes.usedWrapperFunction);\n }\n if (config.fish_lsp_strict_conditional_command_warnings) {\n config.fish_lsp_diagnostic_disable_error_codes.push(ErrorCodes.missingQuietOption);\n }\n if (config.fish_lsp_require_autoloaded_functions_to_have_description) {\n config.fish_lsp_diagnostic_disable_error_codes.push(ErrorCodes.requireAutloadedFunctionHasDescription);\n }\n\n return { config, environmentVariablesUsed };\n}\n\nexport function getDefaultConfiguration(): Config {\n return ConfigSchema.parse({});\n}\n\n/**\n * convert boolean & number shell strings to their correct type\n */\nexport const toBoolean = (s?: string): boolean | undefined =>\n typeof s !== 'undefined' ? s === 'true' || s === '1' : undefined;\n\nexport const toNumber = (s?: string | number): number | undefined =>\n typeof s === 'undefined'\n ? undefined\n : typeof s === 'number' ? s\n : typeof s === 'string' ? parseInt(s, 10) : parseInt(String(s), 10) || undefined;\n\nfunction buildOutput(confd: boolean, result: string[]) {\n // there has to be a `env` index\n const envIndex = process.argv.findIndex(s => s === 'env');\n\n // get the cli command used to generate the env output,\n // which will be included in the comments of the output if `confd` is true\n const command = ['fish-lsp', ...process.argv.slice(envIndex)].join(' ').trimEnd();\n\n // only show built by line if confd, otherwise show result only\n return confd\n ? [\n `# built by \\`${command}\\``,\n 'type -aq fish-lsp || exit',\n 'if status is-interactive',\n result.map(line =>\n line.split('\\n').map(innerLine => ' ' + innerLine).join('\\n').trimEnd(),\n ).join('\\n\\n').trimEnd(),\n 'end',\n ].join('\\n')\n : result.join('\\n').trimEnd();\n}\n\n/**\n * Transforms a fish-lsp env variable value from shell string to array\n */\nexport namespace EnvVariableTransformers {\n\n /**\n * convertValueToShellOutput - Converts a value to valid fish-shell code\n * @param {Config.ConfigValueType} value - the value to convert\n * @returns string - the converted value\n */\n export function convertValueToShellOutput(value: Config.ConfigValueType) {\n if (!Array.isArray(value)) return escapeValue(value) + '\\n';\n\n // For arrays\n if (value.length === 0) return '\\n'; // empty array -> ''\n return value.map(v => escapeValue(v)).join(' ') + '\\n'; // escape and join array\n }\n\n export function getDefaultValueAsShellOutput(\n key: Config.ConfigKeyType,\n opts: { json: boolean; } = { json: false },\n ) {\n const value = Config.getDefaultValue(key);\n if (opts.json) {\n return JSON.stringify(value, null, 2);\n }\n return convertValueToShellOutput(value);\n }\n\n export function getEnvVariableJsonObject(\n result: { [k in Config.ConfigKeyType]: Config.ConfigValueType },\n key: Config.ConfigKeyType,\n value?: Config.ConfigValueType,\n ) {\n result[key] = value ?? config[key];\n return result;\n }\n}\n\n/**\n * Handles building the output for the `fish-lsp env` command\n */\nexport function handleEnvOutput(\n outputType: 'show' | 'create' | 'showDefault',\n callbackfn: (str: string) => void = (str) => logger.logToStdout(str),\n opts: {\n only: string[] | undefined;\n confd: boolean;\n comments: boolean;\n global: boolean;\n local: boolean;\n export: boolean;\n json: boolean;\n } = SubcommandEnv.defaultHandlerOptions,\n) {\n const command = getEnvVariableCommand(opts.global, opts.local, opts.export);\n const result: string[] = [];\n\n const variables = PrebuiltDocumentationMap\n .getByType('variable', 'fishlsp')\n .filter((v) => EnvVariableJson.is(v) ? !v.isDeprecated : false)\n .map(v => v as EnvVariableJson);\n\n const getEnvVariableJsonObject = (keyName: string): EnvVariableJson =>\n variables.find(entry => entry.name === keyName)!;\n\n // Converts a value to valid fish-shell code\n const convertValueToShellOutput = (value: Config.ConfigValueType) => {\n if (!Array.isArray(value)) return escapeValue(value) + '\\n';\n\n // For arrays\n if (value.length === 0) return '\\n'; // empty array -> ''\n return value.map(v => escapeValue(v)).join(' ') + '\\n'; // escape and join array\n };\n\n // Gets the default value for an environment variable, from the zod schema\n const getDefaultValueAsShellOutput = (key: Config.ConfigKeyType) => {\n const value = Config.getDefaultValue(key);\n if (opts.json) {\n return JSON.stringify(value, null, 2);\n }\n return convertValueToShellOutput(value);\n };\n\n // Builds the line (with its comment if needed) for a fish_lsp_* variable.\n // Does not include the value\n const buildBasicLine = (\n entry: EnvVariableJson,\n command: EnvVariableCommand,\n key: Config.ConfigKeyType,\n ) => {\n if (!opts.comments) return `${command} ${key} `;\n return [\n EnvVariableJson.toCliOutput(entry),\n `${command} ${key} `,\n ].join('\\n');\n };\n\n // builds the output for a fish_lsp_* variable (including the comments, and valid shell code)\n const buildOutputSection = (\n entry: EnvVariableJson,\n command: EnvVariableCommand,\n key: Config.ConfigKeyType,\n value: Config.ConfigValueType,\n ) => {\n let line = buildBasicLine(entry, command, key);\n switch (outputType) {\n case 'show':\n line += convertValueToShellOutput(value);\n break;\n case 'showDefault':\n line += getDefaultValueAsShellOutput(key);\n break;\n case 'create':\n default:\n line += '\\n';\n break;\n }\n return line;\n };\n\n if (opts.json) {\n const jsonOutput: Record = {};\n for (const item of Object.entries(config)) {\n const [key, value] = item;\n if (opts.only && !opts.only.includes(key)) continue;\n switch (outputType) {\n case 'create':\n jsonOutput[key] = config[key as keyof Config];\n continue;\n case 'showDefault':\n jsonOutput[key] = Config.getDefaultValue(key as keyof Config);\n continue;\n case 'show':\n default:\n jsonOutput[key] = value;\n continue;\n }\n }\n callbackfn(JSON.stringify(jsonOutput, null, 2));\n return JSON.stringify(jsonOutput, null, 2);\n }\n\n // show - output what is currently being used\n // create - output the default value\n // showDefault - output the default value\n for (const item of Object.entries(config)) {\n const [key, value] = item;\n if (opts.only && !opts.only.includes(key)) continue;\n const configKey = key as keyof Config;\n const entry = getEnvVariableJsonObject(key);\n const line = buildOutputSection(entry, command, configKey, value);\n result.push(line);\n }\n\n const output = buildOutput(opts.confd, result);\n callbackfn(output);\n return output;\n}\n\n/*************************************\n ******* formatting helpers ********\n ************************************/\n\nfunction escapeValue(value: string | number | boolean): string {\n if (typeof value === 'string') {\n // for config values that are variables, surround w/ -> \"\n if (value.startsWith('$__fish')) return `\"${value}\"`;\n if (value === '') return \"''\"; // empty string -> ''\n // Replace special characters with their escaped equivalents\n return `'${value.replace(/\\\\/g, '\\\\\\\\').replace(/\\t/g, '\\\\t').replace(/'/g, \"\\\\'\")}'`;\n } else {\n // Return non-string types as they are\n return value.toString();\n }\n}\n\ntype EnvVariableCommand = 'set -g' | 'set -l' | 'set -gx' | 'set -lx' | 'set' | 'set -x';\n/**\n * getEnvVariableCommand - returns the correct command for setting environment variables\n * in fish-shell. Used for generating `fish-lsp env` output. Result string will be\n * either `set -g`, `set -l`, `set -gx`, or `set -lx`, depending on the flags passed.\n * ___\n * ```fish\n * >_ fish-lsp env --no-global --no-export --no-comments | head -n 1\n * set -l fish_lsp_enabled_handlers\n * ```\n * ___\n * @param {boolean} useGlobal - whether to use the global flag\n * @param {boolean} useLocal - allows for skipping the local flag\n * @param {boolean} useExport - whether to use the export flag\n * @returns {string} - the correct command for setting environment variables\n */\nfunction getEnvVariableCommand(useGlobal: boolean, useLocal: boolean, useExport: boolean): EnvVariableCommand {\n let command = 'set';\n command = useGlobal ? `${command} -g` : useLocal ? `${command} -l` : command;\n command = useExport ? command.endsWith('-g') || command.endsWith('-l') ? `${command}x` : `${command} -x` : command;\n return command as 'set -g' | 'set -l' | 'set -gx' | 'set -lx' | 'set' | 'set -x';\n}\n\nexport const FormatOptions: FormattingOptions = {\n insertSpaces: true,\n tabSize: 4,\n};\n\n/********************************************\n *** Config ***\n *******************************************/\nexport namespace Config {\n\n // eslint-disable-next-line prefer-const\n export let isWebServer = false;\n\n /**\n * fixPopups - updates the `config.fish_lsp_show_client_popups` value based on the 3 cases:\n * - cli flags include 'popups' -> directly sets `fish_lsp_show_client_popups`\n * - `config.fish_lsp_enabled_handlers`/`config.fish_lsp_disabled_handlers` includes 'popups'\n * - if both set && env doesn't set popups -> disable popups\n * - if enabled && env doesn't set popups-> enable popups\n * - if disabled && env doesn't set popups -> disable popups\n * - if env sets popups -> use env for popups && don't override with handler\n * - `config.fish_lsp_show_client_popups` is set in the environment variables\n * @param {string[]} enabled - the cli flags that are enabled\n * @param {string[]} disabled - the cli flags that are disabled\n * @returns {void}\n */\n export function fixPopups(enabled: string[], disabled: string[]): void {\n /*\n * `enabled/disabled` cli flag arrays are used instead of `configHandlers`\n * because `configHandlers` always sets `popups` to true\n */\n if (enabled.includes('popups') || disabled.includes('popups')) {\n if (enabled.includes('popups')) config.fish_lsp_show_client_popups = true;\n if (disabled.includes('popups')) config.fish_lsp_show_client_popups = false;\n return;\n }\n\n /**\n * `configHandlers.popups` is set to false, so popups are disabled\n */\n if (configHandlers.popups === false) {\n config.fish_lsp_show_client_popups = false;\n return;\n }\n\n // envValue is the value of `process.env.fish_lsp_show_client_popups`\n const envValue = toBoolean(process.env.fish_lsp_show_client_popups);\n\n // check error case where both are set\n if (\n config.fish_lsp_enabled_handlers.includes('popups')\n && config.fish_lsp_disabled_handlers.includes('popups')\n ) {\n if (envValue) {\n config.fish_lsp_show_client_popups = envValue;\n return;\n } else {\n config.fish_lsp_show_client_popups = false;\n return;\n }\n }\n\n /**\n * `process.env.fish_lsp_show_client_popups` is not set, and\n * `fish_lsp_enabled_handlers/fish_lsp_disabled_handlers` includes 'popups'\n */\n if (typeof envValue === 'undefined') {\n if (config.fish_lsp_enabled_handlers.includes('popups')) {\n config.fish_lsp_show_client_popups = true;\n return;\n }\n /** config.fish_lsp_disabled_handlers is from the fish env */\n if (config.fish_lsp_disabled_handlers.includes('popups')) {\n config.fish_lsp_show_client_popups = false;\n return;\n }\n }\n\n // `process.env.fish_lsp_show_client_popups` is set and 'popups' is enabled/disabled in the handlers\n return;\n }\n\n export type ConfigValueType = string | number | boolean | string[] | number[]; // Config[keyof Config] | string[] | number[];\n export type ConfigKeyType = keyof Config;\n\n export function getDefaultValue(key: keyof Config): Config[keyof Config] {\n const defaults = ConfigSchema.parse({});\n return defaults[key];\n }\n\n export function getDocsForKey(key: keyof Config): string {\n const entry = PrebuiltDocumentationMap.getByType('variable', 'fishlsp').find(e => e.name === key);\n if (entry) {\n return entry.description;\n }\n return '';\n }\n\n /**\n * Builder for the `envDocs` object\n */\n const getDocsObj = (): Record => {\n const docsObj = {} as Record;\n const entries = PrebuiltDocumentationMap.getByType('variable', 'fishlsp');\n entries.forEach(entry => {\n if (EnvVariableJson.is(entry)) {\n if (entry?.isDeprecated) return;\n docsObj[entry.name as keyof Config] = entry.shortDescription;\n }\n });\n return docsObj;\n };\n\n /**\n * Config.docs[fish_lsp_*]: Documentation for fish_lsp_* variables\n * Used for the `fish-lsp env` cli completions\n */\n export const envDocs: Record = getDocsObj();\n export const allServerFeatures = Array.from([...validHandlers]);\n\n /**\n * All old environment variables mapped to their new key names.\n */\n export const deprecatedKeys: { [deprecated_key: string]: keyof Config; } = {\n ['fish_lsp_logfile']: 'fish_lsp_log_file',\n };\n\n export function isDeprecatedKey(key: string): boolean {\n if (key.trim() === '') return false;\n return Object.keys(deprecatedKeys).includes(key);\n }\n\n // Or use a helper function approach for even better typing\n\n export const allKeys: Array = Object.keys(ConfigSchema.parse({})) as Array;\n\n /**\n * We only need to call this for the `initializationOptions`, but it ensures any string\n * passed in is a valid config key. If the key is not found, it will return undefined.\n *\n * @param {string} key - the key to check\n * @return {keyof Config | undefined} - the key if it exists in the config, or undefined\n */\n export function getEnvVariableKey(key: string): keyof Config | undefined {\n if (key in config) {\n return key as keyof Config;\n }\n if (Object.keys(deprecatedKeys).includes(key)) {\n return deprecatedKeys[key] as keyof Config;\n }\n return undefined;\n }\n\n /**\n * update the `config` object from the `params.initializationOptions` object,\n * where the `params` are `InitializeParams` from the language client.\n * @param {Config | null} initializationOptions - the initialization options from the client\n * @returns {void} updates both the `config` and `configHandlers` objects\n */\n export function updateFromInitializationOptions(initializationOptions: Config | null): void {\n if (!initializationOptions) return;\n ConfigSchema.parse(initializationOptions);\n Object.keys(initializationOptions).forEach((key) => {\n const configKey = getEnvVariableKey(key);\n if (!configKey) return;\n (config[configKey] as any) = initializationOptions[configKey];\n });\n if (initializationOptions.fish_lsp_enabled_handlers) {\n updateHandlers(initializationOptions.fish_lsp_enabled_handlers, true);\n }\n if (initializationOptions.fish_lsp_disabled_handlers) {\n updateHandlers(initializationOptions.fish_lsp_disabled_handlers, false);\n }\n }\n\n /**\n * Call this after updating the `configHandlers` to ensure that all\n * enabled/disabled handlers are set correctly.\n */\n export function fixEnabledDisabledHandlers(): void {\n config.fish_lsp_enabled_handlers = [];\n config.fish_lsp_disabled_handlers = [];\n Object.keys(configHandlers).forEach((key) => {\n const value = configHandlers[key as keyof typeof ConfigHandlerSchema.shape];\n if (!value) {\n config.fish_lsp_disabled_handlers.push(key);\n } else {\n config.fish_lsp_enabled_handlers.push(key);\n }\n });\n }\n\n /**\n * getResultCapabilities - returns the capabilities for the language server based on the\n * Uses both global objects: `config` and `configHandlers`\n * Therefore, these values must be set/updated before calling this function.\n */\n export function getResultCapabilities(): InitializeResult {\n // Extend the serverInfo object with additional information\n const serverInfo = {\n name: 'fish-lsp',\n version: PackageVersion,\n buildTime: getBuildTimeJsonObj()?.timestamp,\n buildPath: getProjectRootPath(),\n } as InitializeResult['serverInfo'];\n\n return {\n capabilities: {\n textDocumentSync: {\n openClose: true,\n change: TextDocumentSyncKind.Incremental,\n save: { includeText: true },\n },\n completionProvider: configHandlers.complete ? {\n resolveProvider: true,\n allCommitCharacters: config.fish_lsp_commit_characters,\n workDoneProgress: false,\n } : undefined,\n hoverProvider: configHandlers.hover,\n definitionProvider: configHandlers.definition,\n implementationProvider: configHandlers.implementation,\n referencesProvider: configHandlers.reference,\n renameProvider: configHandlers.rename,\n documentFormattingProvider: configHandlers.formatting,\n documentRangeFormattingProvider: configHandlers.formatRange,\n foldingRangeProvider: configHandlers.folding,\n selectionRangeProvider: configHandlers.selectionRange,\n codeActionProvider: configHandlers.codeAction ? {\n codeActionKinds: [...AllSupportedActions],\n workDoneProgress: true,\n resolveProvider: true,\n } : undefined,\n executeCommandProvider: configHandlers.executeCommand ? {\n commands: [...AllSupportedActions, ...LspCommands],\n workDoneProgress: true,\n } : undefined,\n documentSymbolProvider: {\n label: 'fish-lsp',\n },\n workspaceSymbolProvider: {\n resolveProvider: true,\n },\n documentHighlightProvider: configHandlers.highlight,\n inlayHintProvider: configHandlers.inlayHint,\n semanticTokensProvider: configHandlers.semanticTokens ? {\n legend: FishSemanticTokens.legend,\n range: true,\n full: { delta: false },\n } : undefined,\n signatureHelpProvider: configHandlers.signature ? { workDoneProgress: false, triggerCharacters: ['.'] } : undefined,\n documentOnTypeFormattingProvider: configHandlers.typeFormatting ? {\n firstTriggerCharacter: '.',\n moreTriggerCharacter: [';', '}', ']', ')'],\n } : undefined,\n // linkedEditingRangeProvider: configHandlers.linkedEditingRange,\n // Add this for workspace folder support:\n workspace: {\n workspaceFolders: {\n supported: true,\n changeNotifications: true,\n },\n },\n },\n serverInfo,\n };\n }\n\n /**\n * *******************************************\n * *** initializeResult ***\n * *******************************************\n * * The `initializeResult` is the result of the `initialize` method\n */\n export function initialize(params: InitializeParams, connection: Connection) {\n updateFromInitializationOptions(params.initializationOptions);\n createServerLogger(config.fish_lsp_log_file, connection.console);\n const result = getResultCapabilities();\n logger.log({ onInitializedResult: result });\n return result;\n }\n}\n\n// create config to be used globally\nexport const { config, environmentVariablesUsed } = getConfigFromEnvironmentVariables();\n"
},
{
"path": "src/diagnostics/buffered-async-cache.ts",
"content": "import { Diagnostic, DocumentUri } from 'vscode-languageserver';\nimport { analyzer } from '../analyze';\nimport { documents, LineSpan, rangeOverlapsLineSpan } from '../document';\nimport { configHandlers } from '../config';\nimport { getDiagnosticsAsync } from './validate';\nimport { connection } from '../utils/startup';\nimport { logger } from '../logger';\nimport { config } from '../config';\n\n/**\n * Buffered async diagnostic cache that:\n * 1. Debounces diagnostic updates to avoid recalculating on every keystroke\n * 2. Processes diagnostics asynchronously with yielding to avoid blocking main thread\n * 3. Supports cancellation of outdated diagnostic calculations\n * 4. Automatically sends diagnostics to the client when ready\n *\n * This provides a significant performance improvement over the synchronous\n * DiagnosticCache, especially for large documents.\n */\nexport class BufferedAsyncDiagnosticCache {\n private cache: Map = new Map();\n private pendingCalculations: Map = new Map();\n private debounceTimers: Map = new Map();\n\n // Debounce delay in milliseconds\n // Diagnostics won't run until user stops typing for this duration\n private readonly DEBOUNCE_MS = 400;\n\n /**\n * Request a diagnostic update for a document.\n * If immediate=false, the update will be debounced.\n * If immediate=true, the update runs right away.\n *\n * @param uri - Document URI to update diagnostics for\n * @param immediate - If true, skip debouncing and run immediately\n */\n requestUpdate(uri: DocumentUri, immediate = false, changedSpan?: LineSpan): void {\n logger.debug({\n message: 'BufferedAsyncDiagnosticCache: Requesting diagnostic update',\n uri,\n immediate,\n changedSpan: {\n start: changedSpan?.start,\n end: changedSpan?.end,\n isFullDocument: changedSpan?.isFullDocument || false,\n },\n diagnostics: this.cache.get(uri)?.map(d => ({\n code: d.code,\n range: d.range.start.line + '-' + d.range.end.line,\n })),\n diagnosticsPending: this.isPending(uri),\n debounceTimer: {\n timer: this.debounceTimers.get(uri),\n has: this.debounceTimers.has(uri),\n },\n });\n if (config.fish_lsp_disabled_handlers.includes('diagnostic')) {\n return;\n }\n // Log the change span for debugging purposes\n if (changedSpan && !changedSpan.isFullDocument) {\n const prev = this.cache.get(uri);\n if (prev && prev.length > 0) {\n const filtered = prev.filter(\n (d) => !rangeOverlapsLineSpan(d.range, changedSpan, 1),\n );\n if (filtered.length !== prev.length && filtered.length > 0) {\n // We removed at least one diagnostic in the edited area.\n // Update cache & immediately send the reduced set so UI clears.\n this.cache.set(uri, filtered);\n connection.sendDiagnostics({ uri, diagnostics: filtered });\n\n logger.debug(\n 'BufferedAsyncDiagnosticCache: Optimistically cleared stale diagnostics in edited span',\n { uri, removed: prev.length - filtered.length },\n );\n }\n }\n }\n\n // Clear any existing debounce timer for this URI\n const existingTimer = this.debounceTimers.get(uri);\n if (existingTimer) {\n clearTimeout(existingTimer);\n this.debounceTimers.delete(uri);\n logger.debug('BufferedAsyncDiagnosticCache: Cleared existing debounce timer', { uri });\n }\n\n if (immediate) {\n // Run immediately without debouncing\n this.update(uri);\n } else {\n // Debounce: wait DEBOUNCE_MS before running\n const timer = setTimeout(() => {\n this.update(uri);\n this.debounceTimers.delete(uri);\n }, this.DEBOUNCE_MS);\n\n this.debounceTimers.set(uri, timer);\n }\n }\n\n /**\n * Internal method to actually compute and update diagnostics.\n * Cancels any pending calculation for the same URI before starting a new one.\n *\n * @param uri - Document URI to compute diagnostics for\n */\n private async update(uri: DocumentUri): Promise {\n // Cancel any existing diagnostic calculation for this URI\n const existingController = this.pendingCalculations.get(uri);\n if (existingController) {\n existingController.abort();\n this.pendingCalculations.delete(uri);\n }\n\n // Check if diagnostics are disabled\n if (!configHandlers.diagnostic) {\n connection.sendDiagnostics({ uri, diagnostics: [] });\n return;\n }\n\n const doc = documents.get(uri);\n if (!doc) {\n logger.debug('BufferedAsyncDiagnosticCache: Document not found', { uri });\n connection.sendDiagnostics({ uri, diagnostics: [] });\n return;\n }\n\n const cachedDoc = analyzer.ensureCachedDocument(doc);\n if (!cachedDoc?.root) {\n logger.debug('BufferedAsyncDiagnosticCache: Document has no syntax tree', { uri });\n connection.sendDiagnostics({ uri, diagnostics: [] });\n return;\n }\n\n // Create abort controller for this calculation\n // This allows us to cancel if the document changes again\n const controller = new AbortController();\n this.pendingCalculations.set(uri, controller);\n\n try {\n // Run async diagnostic calculation (non-blocking!)\n // This will yield to the event loop periodically\n const diagnostics = await getDiagnosticsAsync(\n cachedDoc.root,\n doc,\n controller.signal,\n );\n\n // Check if the calculation was aborted while running\n if (controller.signal.aborted) {\n logger.debug('BufferedAsyncDiagnosticCache: Calculation was cancelled', { uri });\n connection.sendDiagnostics({ uri, diagnostics: [] });\n return;\n }\n\n // Update cache\n this.cache.set(uri, diagnostics);\n\n // Send diagnostics to client\n connection.sendDiagnostics({ uri, diagnostics });\n\n logger.debug('BufferedAsyncDiagnosticCache: Diagnostics updated', {\n uri,\n count: diagnostics.length,\n });\n } catch (error) {\n // Only log errors if the calculation wasn't aborted\n if (!controller.signal.aborted) {\n logger.error('BufferedAsyncDiagnosticCache: Error calculating diagnostics', {\n uri,\n error: error instanceof Error ? error.message : String(error),\n });\n }\n } finally {\n // Clean up the pending calculation\n this.pendingCalculations.delete(uri);\n }\n }\n\n /**\n * Delete diagnostics for a document.\n * Cancels any pending calculations and clears cached diagnostics.\n * Sends empty diagnostics array to client to clear UI.\n *\n * @param uri - Document URI to delete diagnostics for\n */\n delete(uri: DocumentUri): void {\n // Cancel debounce timer if exists\n const timer = this.debounceTimers.get(uri);\n if (timer) {\n clearTimeout(timer);\n this.debounceTimers.delete(uri);\n }\n\n // Cancel pending calculation if exists\n const controller = this.pendingCalculations.get(uri);\n if (controller) {\n controller.abort();\n this.pendingCalculations.delete(uri);\n }\n\n // Remove from cache\n this.cache.delete(uri);\n\n // Clear diagnostics in client UI\n connection.sendDiagnostics({ uri, diagnostics: [] });\n\n logger.debug('BufferedAsyncDiagnosticCache: Diagnostics deleted', { uri });\n }\n\n /**\n * Clear all diagnostics.\n * Cancels all pending calculations and timers.\n */\n clear(): void {\n // Cancel all debounce timers\n this.debounceTimers.forEach(timer => clearTimeout(timer));\n this.debounceTimers.clear();\n\n // Cancel all pending calculations\n this.pendingCalculations.forEach(controller => controller.abort());\n this.pendingCalculations.clear();\n\n // Clear cache\n this.cache.clear();\n\n logger.debug('BufferedAsyncDiagnosticCache: All diagnostics cleared');\n }\n\n /**\n * Get cached diagnostics for a document.\n * Returns undefined if not cached.\n * Note: This returns the cached value immediately, it does not trigger computation.\n *\n * @param uri - Document URI to get diagnostics for\n * @returns Cached diagnostics or undefined\n */\n get(uri: DocumentUri): Diagnostic[] | undefined {\n return this.cache.get(uri);\n }\n\n /**\n * Check if a document has cached diagnostics.\n *\n * @param uri - Document URI to check\n * @returns true if diagnostics are cached\n */\n has(uri: DocumentUri): boolean {\n return this.cache.has(uri);\n }\n\n /**\n * Get the number of pending diagnostic calculations.\n * Useful for debugging or status indicators.\n *\n * @returns Number of documents with pending calculations\n */\n get pendingCount(): number {\n return this.pendingCalculations.size;\n }\n\n /**\n * Check if diagnostics are currently being calculated for a document.\n *\n * @param uri - Document URI to check\n * @returns true if diagnostics are being calculated\n */\n isPending(uri: DocumentUri): boolean {\n return this.pendingCalculations.has(uri);\n }\n\n public setForTesting(uri: DocumentUri, diagnostics: Diagnostic[]) {\n this.cache.set(uri, diagnostics);\n }\n}\n"
},
{
"path": "src/diagnostics/comments-handler.ts",
"content": "import { SyntaxNode } from 'web-tree-sitter';\nimport { isComment } from '../utils/node-types';\nimport { ErrorCodes } from './error-codes';\nimport { config } from '../config';\nimport { Position } from 'vscode-languageserver';\n\nexport type DiagnosticAction = 'enable' | 'disable';\nexport type DiagnosticTarget = 'line' | 'next-line';\n\nexport interface DiagnosticComment {\n action: DiagnosticAction;\n target: DiagnosticTarget;\n codes: ErrorCodes.CodeTypes[];\n lineNumber: number;\n invalidCodes?: string[]; // Track any invalid codes found during parsing\n}\n\nexport interface DiagnosticState {\n enabledCodes: Set;\n comment: DiagnosticComment;\n invalidCodes?: string[];\n}\n\n/**\n * Regular expression to match fish-lsp diagnostic control comments\n * Matches patterns like:\n * # @fish-lsp-disable\n * # @fish-lsp-enable\n * # @fish-lsp-disable 1001 1002\n * # @fish-lsp-enable 1001\n * # @fish-lsp-disable-next-line\n * # @fish-lsp-disable-next-line 3002 3001\n */\nexport const DIAGNOSTIC_COMMENT_REGEX = /^#\\s*@fish-lsp-(disable|enable)(?:-(next-line))?\\s*([0-9\\s]*)?$/;\n\n/**\n * Checks if a node is a diagnostic control comment\n * @param node The syntax node to check\n * @returns true if the node is a diagnostic control comment\n */\nexport function isDiagnosticComment(node: SyntaxNode): boolean {\n if (!isComment(node)) return false;\n return DIAGNOSTIC_COMMENT_REGEX.test(node.text.trim());\n}\n\nexport function isValidErrorCode(code: number): code is ErrorCodes.CodeTypes {\n return Object.values(ErrorCodes).includes(code as ErrorCodes.CodeTypes);\n}\n\n/**\n * Parses a diagnostic comment node into its components\n * @param node The syntax node to parse\n * @returns DiagnosticComment object containing the parsed information\n */\nexport function parseDiagnosticComment(node: SyntaxNode): DiagnosticComment | null {\n if (!isDiagnosticComment(node)) return null;\n\n const match = node.text.trim().match(DIAGNOSTIC_COMMENT_REGEX);\n if (!match) return null;\n\n const [, action, nextLine, codesStr] = match;\n\n const codeStrings = codesStr ? codesStr.trim().split(/\\s+/) : [];\n\n // Parse the diagnostic codes if present\n const parsedCodes = codeStrings\n .map(codeStr => parseInt(codeStr, 10))\n .filter(code => !isNaN(code));\n\n const validCodes: ErrorCodes.CodeTypes[] = [];\n const invalidCodes: string[] = [];\n\n codeStrings.forEach((codeStr, idx) => {\n const code = parsedCodes[idx];\n if (code && !isNaN(code) && isValidErrorCode(code)) {\n validCodes.push(code);\n } else {\n invalidCodes.push(codeStr);\n }\n });\n\n return {\n action: action as DiagnosticAction,\n target: nextLine ? 'next-line' : 'line',\n codes: validCodes.length > 0 ? validCodes : ErrorCodes.allErrorCodes,\n lineNumber: node.startPosition.row,\n invalidCodes: invalidCodes.length > 0 ? invalidCodes : undefined,\n };\n}\n\n/**\n * Represents a diagnostic control point that affects code diagnostics\n */\ninterface DiagnosticControlPoint {\n line: number;\n action: DiagnosticAction;\n codes: ErrorCodes.CodeTypes[];\n isNextLine?: boolean;\n}\n\n/**\n * Structure to track diagnostic state at a specific line\n */\ninterface LineState {\n enabledCodes: Set;\n}\n\nexport class DiagnosticCommentsHandler {\n // Original stack-based state for compatibility during parsing\n private stateStack: DiagnosticState[] = [];\n\n // Track all control points (sorted by line number) for position-based lookups\n private controlPoints: DiagnosticControlPoint[] = [];\n\n // Map of line numbers to their effective states (calculated at the end)\n private lineStateMap: Map = new Map();\n\n // Track invalid codes for reporting\n public invalidCodeWarnings: Map = new Map();\n\n // Cached enabled comments for current state\n public enabledComments: ErrorCodes.CodeTypes[] = [];\n\n constructor() {\n // Initialize with global state\n this.pushState(this.initialState);\n this.enabledComments = Array.from(this.currentState.enabledCodes);\n }\n\n private get initialState(): DiagnosticState {\n return {\n enabledCodes: new Set(this.globalEnabledCodes()),\n comment: {\n action: 'enable',\n target: 'line',\n codes: this.globalEnabledCodes(),\n lineNumber: -1,\n },\n };\n }\n\n private get rootState(): DiagnosticState {\n return this.stateStack[0]!;\n }\n\n private get currentState(): DiagnosticState {\n return this.stateStack[this.stateStack.length - 1]!;\n }\n\n private globalEnabledCodes(): ErrorCodes.CodeTypes[] {\n const codes = ErrorCodes.allErrorCodes;\n if (config.fish_lsp_diagnostic_disable_error_codes.length > 0) {\n return codes.filter(\n code => !config.fish_lsp_diagnostic_disable_error_codes.includes(code),\n ).filter(code => ErrorCodes.nonDeprecatedErrorCodes.some(e => e.code === code));\n }\n return codes.filter(code =>\n ErrorCodes.nonDeprecatedErrorCodes.some(e => e.code === code),\n );\n }\n\n private pushState(state: DiagnosticState) {\n this.stateStack.push(state);\n }\n\n private popState() {\n if (this.stateStack.length > 1) { // Keep at least the global state\n this.stateStack.pop();\n this.enabledComments = Array.from(this.currentState.enabledCodes);\n }\n }\n\n /**\n * Process a node for diagnostic comments\n * This maintains both the stack state and records control points\n */\n public handleNode(node: SyntaxNode): void {\n // Clean up any expired next-line comments\n this.cleanupNextLineComments(node.startPosition.row);\n\n // Early return if not a diagnostic comment\n if (!isDiagnosticComment(node)) {\n return;\n }\n\n const comment = parseDiagnosticComment(node);\n if (!comment) return;\n\n // Track invalid codes if present\n if (comment.invalidCodes && comment.invalidCodes.length > 0) {\n this.invalidCodeWarnings.set(comment.lineNumber, comment.invalidCodes);\n }\n\n // Process the comment for both backward compatibility and position-based lookups\n this.processComment(comment);\n }\n\n private processComment(comment: DiagnosticComment) {\n // Update stack-based state (for backward compatibility)\n const newEnabledCodes = new Set(this.currentState.enabledCodes);\n\n if (comment.action === 'disable') {\n comment.codes.forEach(code => newEnabledCodes.delete(code));\n } else {\n comment.codes.forEach(code => newEnabledCodes.add(code));\n }\n\n const newState: DiagnosticState = {\n enabledCodes: newEnabledCodes,\n comment,\n invalidCodes: comment.invalidCodes,\n };\n\n // Update control points for position-based lookups\n const controlPoint: DiagnosticControlPoint = {\n line: comment.lineNumber,\n action: comment.action,\n codes: comment.codes,\n isNextLine: comment.target === 'next-line',\n };\n\n this.controlPoints.push(controlPoint);\n // Keep control points sorted by line number\n this.controlPoints.sort((a, b) => a.line - b.line);\n\n if (comment.target === 'next-line') {\n // For next-line, we'll push a new state that will be popped after the line\n this.pushState(newState);\n } else {\n // For regular comments, we'll replace the current state\n if (this.stateStack.length > 1) {\n this.popState(); // Remove the current state\n }\n this.pushState(newState);\n }\n\n this.enabledComments = Array.from(newEnabledCodes);\n }\n\n private cleanupNextLineComments(currentLine: number) {\n while (\n this.stateStack.length > 1 && // Keep global state\n this.currentState.comment.target === 'next-line' &&\n currentLine > this.currentState.comment.lineNumber + 1\n ) {\n this.popState();\n }\n }\n\n /**\n * This method is called when all nodes have been processed\n * It computes the effective state for each line in the document\n */\n public finalizeStateMap(maxLine: number): void {\n // Start with initial state\n let currentState: LineState = {\n enabledCodes: new Set(this.globalEnabledCodes()),\n };\n\n // Process all regular control points first\n const regularPoints = this.controlPoints.filter(p => !p.isNextLine);\n const nextLinePoints: Map = new Map();\n\n // Group next-line control points by target line\n for (const point of this.controlPoints) {\n if (point.isNextLine) {\n const targetLine = point.line + 1;\n const existing = nextLinePoints.get(targetLine) || [];\n existing.push({ ...point, line: targetLine });\n nextLinePoints.set(targetLine, existing);\n }\n }\n\n // Build line by line state\n for (let line = 0; line <= maxLine; line++) {\n // Apply regular control points for this line\n for (const point of regularPoints) {\n if (point.line <= line) {\n this.applyControlPointToState(currentState, point);\n }\n }\n\n // Save the state before applying next-line directives\n const baseState = {\n enabledCodes: new Set(currentState.enabledCodes),\n };\n\n // Apply next-line directives for this line only\n const nextLineDirs = nextLinePoints.get(line) || [];\n for (const directive of nextLineDirs) {\n this.applyControlPointToState(currentState, directive);\n }\n\n // Store state for this line\n this.lineStateMap.set(line, {\n enabledCodes: new Set(currentState.enabledCodes),\n });\n\n // Restore base state after next-line directives\n if (nextLineDirs.length > 0) {\n currentState = baseState;\n }\n }\n }\n\n private applyControlPointToState(state: LineState, point: DiagnosticControlPoint): void {\n if (point.action === 'disable') {\n // Disable specified codes\n for (const code of point.codes) {\n state.enabledCodes.delete(code);\n }\n } else {\n // Enable specified codes\n for (const code of point.codes) {\n state.enabledCodes.add(code);\n }\n }\n }\n\n public isCodeEnabledAtNode(code: ErrorCodes.CodeTypes, node: SyntaxNode): boolean {\n const position = { line: node.startPosition.row, character: node.startPosition.column };\n return this.isCodeEnabledAtPosition(code, position);\n }\n\n /**\n * Check if a specific diagnostic code is enabled at a given position\n * Will use the pre-computed state if available, otherwise computes on-demand\n */\n public isCodeEnabledAtPosition(code: ErrorCodes.CodeTypes, position: Position): boolean {\n if (this.lineStateMap.has(position.line)) {\n // Use pre-computed state if available\n const state = this.lineStateMap.get(position.line)!;\n return state.enabledCodes.has(code);\n }\n\n // Compute state on-demand if not pre-computed\n return this.computeStateAtPosition(position).enabledCodes.has(code);\n }\n\n /**\n * Compute state at a position on-demand (used if finalizeStateMap hasn't been called)\n */\n private computeStateAtPosition(position: Position): LineState {\n // Start with global state\n const state: LineState = {\n enabledCodes: new Set(this.globalEnabledCodes()),\n };\n\n // Apply all regular control points up to this position\n for (const point of this.controlPoints) {\n if (point.line > position.line) {\n break; // Skip control points after this position\n }\n\n if (!point.isNextLine && point.line <= position.line) {\n this.applyControlPointToState(state, point);\n }\n\n // Apply next-line directives for the specific line\n if (point.isNextLine && point.line + 1 === position.line) {\n this.applyControlPointToState(state, { ...point, line: position.line });\n }\n }\n\n return state;\n }\n\n /**\n * Check if a specific diagnostic code is enabled in the current state\n * This is for backward compatibility during parsing\n */\n public isCodeEnabled(code: ErrorCodes.CodeTypes): boolean {\n return this.currentState.enabledCodes.has(code);\n }\n\n public isRootEnabled(code: ErrorCodes.CodeTypes): boolean {\n return this.rootState.enabledCodes.has(code);\n }\n\n public getStackDepth(): number {\n return this.stateStack.length;\n }\n\n public getCurrentState(): DiagnosticState {\n return this.currentState;\n }\n\n public * stateIterator(): IterableIterator {\n for (const state of this.stateStack) {\n yield state;\n }\n }\n\n /**\n * For debugging/testing - get verbose state information\n */\n public getCurrentStateVerbose() {\n const currentState = this.getCurrentState();\n const disabledCodes = ErrorCodes.allErrorCodes.filter(e => !currentState.enabledCodes.has(e));\n const enabledCodes = Array.from(currentState.enabledCodes)\n .map(e => ErrorCodes.codes[e].code)\n .concat(disabledCodes)\n .sort((a, b) => a - b)\n .map(item => {\n if (disabledCodes.includes(item)) return '....';\n return item;\n })\n .join(' | ');\n\n const invalidCodes = Array.from(this.invalidCodeWarnings.entries())\n .map(([line, codes]) => `${line}: ${codes.join(' | ')}`);\n\n const lineStates = Array.from(this.lineStateMap.entries())\n .map(([line, state]) => `Line ${line}: ${Array.from(state.enabledCodes).length} enabled codes`);\n\n return {\n depth: this.getStackDepth(),\n enabledCodes: enabledCodes,\n invalidCodes: invalidCodes,\n currentState: {\n action: currentState.comment.action,\n target: currentState.comment.target,\n codes: currentState.comment?.codes.join(' | '),\n lineNumber: currentState.comment.lineNumber,\n },\n controlPoints: this.controlPoints.length,\n lineStates: lineStates.slice(0, 10), // Show first 10 for brevity\n };\n }\n}\n"
},
{
"path": "src/diagnostics/diagnostic-ranges.ts",
"content": "import { SyntaxNode } from 'web-tree-sitter';\nimport { ErrorCodes } from './error-codes';\nimport { config } from '../config';\nimport { isComment } from '../utils/node-types';\nimport { nodesGen } from '../utils/tree-sitter';\n\n/**\n * Represents a range where a specific diagnostic code is disabled\n */\nexport interface DisabledRange {\n startLine: number;\n endLine: number; // -1 means until end of file\n code: ErrorCodes.CodeTypes; // Single code per range for clarity\n}\n\n/**\n * Result of pre-computing diagnostic ranges\n */\nexport interface DiagnosticRangesResult {\n /** Ranges where specific codes are disabled (one range per code) */\n disabledRanges: DisabledRange[];\n /** Lines with invalid diagnostic codes in comments (for reporting) */\n invalidCodeLines: Map;\n /** Total number of diagnostic comments found */\n commentCount: number;\n /** Time taken to compute ranges (ms) */\n computeTimeMs: number;\n}\n\n/**\n * Regular expression to match fish-lsp diagnostic control comments\n */\nconst DIAGNOSTIC_COMMENT_REGEX = /^#\\s*@fish-lsp-(disable|enable)(?:-(next-line))?\\s*([0-9\\s]*)?$/;\n\n/**\n * Check if a code is a valid ErrorCode\n */\nfunction isValidErrorCode(code: number): code is ErrorCodes.CodeTypes {\n return Object.values(ErrorCodes).includes(code as ErrorCodes.CodeTypes);\n}\n\n/**\n * Get the globally enabled codes based on config\n */\nfunction getGlobalEnabledCodes(): Set {\n const codes = ErrorCodes.allErrorCodes.filter(code =>\n ErrorCodes.nonDeprecatedErrorCodes.some(e => e.code === code),\n );\n\n if (config.fish_lsp_diagnostic_disable_error_codes.length > 0) {\n return new Set(\n codes.filter(code => !config.fish_lsp_diagnostic_disable_error_codes.includes(code)),\n );\n }\n\n return new Set(codes);\n}\n\ninterface ParsedComment {\n action: 'enable' | 'disable';\n isNextLine: boolean;\n codes: ErrorCodes.CodeTypes[];\n allCodes: boolean; // true if no specific codes were specified (applies to all)\n lineNumber: number;\n invalidCodes: string[];\n}\n\n/**\n * Parse a diagnostic comment from a syntax node\n */\nfunction parseDiagnosticComment(node: SyntaxNode): ParsedComment | null {\n if (!isComment(node)) return null;\n\n const match = node.text.trim().match(DIAGNOSTIC_COMMENT_REGEX);\n if (!match) return null;\n\n const [, action, nextLine, codesStr] = match;\n\n const codeStrings = codesStr ? codesStr.trim().split(/\\s+/).filter(s => s.length > 0) : [];\n\n const validCodes: ErrorCodes.CodeTypes[] = [];\n const invalidCodes: string[] = [];\n\n for (const codeStr of codeStrings) {\n const code = parseInt(codeStr, 10);\n if (!isNaN(code) && isValidErrorCode(code)) {\n validCodes.push(code);\n } else if (codeStr.length > 0) {\n invalidCodes.push(codeStr);\n }\n }\n\n // If no codes specified, it applies to ALL codes\n const allCodes = validCodes.length === 0;\n const codes = allCodes ? Array.from(getGlobalEnabledCodes()) : validCodes;\n\n return {\n action: action as 'enable' | 'disable',\n isNextLine: !!nextLine,\n codes,\n allCodes,\n lineNumber: node.startPosition.row,\n invalidCodes,\n };\n}\n\n/**\n * Pre-compute diagnostic disabled ranges from the syntax tree.\n *\n * Handles cascading/overlapping disables correctly:\n * - `# @fish-lsp-disable 1001` on line 10 disables 1001 from line 10 onwards\n * - `# @fish-lsp-disable 1002` on line 20 ALSO disables 1002, but 1001 stays disabled\n * - `# @fish-lsp-enable` (no codes) re-enables ALL codes\n * - `# @fish-lsp-enable 1001` only re-enables 1001\n *\n * @param root - The root syntax node of the document\n * @param maxLine - The maximum line number in the document\n * @returns DiagnosticRangesResult with computed ranges\n */\nexport function computeDiagnosticRanges(root: SyntaxNode, maxLine: number): DiagnosticRangesResult {\n const startTime = performance.now();\n\n const disabledRanges: DisabledRange[] = [];\n const invalidCodeLines = new Map();\n let commentCount = 0;\n\n // Track currently active disables PER CODE (cascading support)\n // Map: code -> startLine where it was disabled\n const activeDisables = new Map();\n\n // Collect all diagnostic comments first\n const comments: ParsedComment[] = [];\n\n for (const node of nodesGen(root)) {\n if (!isComment(node)) continue;\n\n const parsed = parseDiagnosticComment(node);\n if (parsed) {\n comments.push(parsed);\n commentCount++;\n\n if (parsed.invalidCodes.length > 0) {\n invalidCodeLines.set(parsed.lineNumber, parsed.invalidCodes);\n }\n }\n }\n\n // Sort comments by line number\n comments.sort((a, b) => a.lineNumber - b.lineNumber);\n\n // Process comments to build ranges\n for (const comment of comments) {\n if (comment.isNextLine) {\n // Next-line comments create single-line disabled ranges\n if (comment.action === 'disable') {\n for (const code of comment.codes) {\n disabledRanges.push({\n startLine: comment.lineNumber + 1,\n endLine: comment.lineNumber + 1,\n code,\n });\n }\n }\n // Note: enable-next-line is rare and would temporarily re-enable within a disabled block\n // For simplicity, we don't support this edge case\n } else {\n // Regular disable/enable comments\n if (comment.action === 'disable') {\n // Start tracking each code independently\n for (const code of comment.codes) {\n if (!activeDisables.has(code)) {\n // Only start a new range if not already disabled\n activeDisables.set(code, comment.lineNumber);\n }\n // If already disabled, the existing disable continues (no action needed)\n }\n } else {\n // Enable comment - close ranges for the specified codes\n for (const code of comment.codes) {\n const startLine = activeDisables.get(code);\n if (startLine !== undefined) {\n // Close the range for this code\n disabledRanges.push({\n startLine,\n endLine: comment.lineNumber - 1,\n code,\n });\n activeDisables.delete(code);\n }\n }\n }\n }\n }\n\n // Close any remaining active disables (extend to end of file)\n for (const [code, startLine] of activeDisables.entries()) {\n disabledRanges.push({\n startLine,\n endLine: maxLine,\n code,\n });\n }\n\n const computeTimeMs = performance.now() - startTime;\n\n return {\n disabledRanges,\n invalidCodeLines,\n commentCount,\n computeTimeMs,\n };\n}\n\n/**\n * Fast lookup class for checking if a diagnostic code is enabled at a specific line\n */\nexport class DiagnosticRangeChecker {\n private disabledRanges: DisabledRange[];\n private globalEnabledCodes: Set;\n\n // Optimized: Pre-compute a map of line -> disabled codes for fast lookup\n private lineDisabledCodes: Map> = new Map();\n private maxPrecomputedLine: number = -1;\n\n constructor(ranges: DiagnosticRangesResult, maxLine?: number) {\n this.disabledRanges = ranges.disabledRanges;\n this.globalEnabledCodes = getGlobalEnabledCodes();\n\n // Pre-compute line lookup map if maxLine is provided\n if (maxLine !== undefined && maxLine <= 10000) {\n this.precomputeLineLookup(maxLine);\n }\n }\n\n /**\n * Pre-compute disabled codes for each line for O(1) lookup\n */\n private precomputeLineLookup(maxLine: number): void {\n for (let line = 0; line <= maxLine; line++) {\n const disabledCodes = new Set();\n\n for (const range of this.disabledRanges) {\n const endLine = range.endLine === -1 ? maxLine : range.endLine;\n if (line >= range.startLine && line <= endLine) {\n disabledCodes.add(range.code);\n }\n }\n\n if (disabledCodes.size > 0) {\n this.lineDisabledCodes.set(line, disabledCodes);\n }\n }\n\n this.maxPrecomputedLine = maxLine;\n }\n\n /**\n * Check if a specific diagnostic code is enabled at a given line\n * O(1) if pre-computed, O(ranges) otherwise\n */\n isCodeEnabledAtLine(code: ErrorCodes.CodeTypes, line: number): boolean {\n // Check if globally disabled first\n if (!this.globalEnabledCodes.has(code)) {\n return false;\n }\n\n // Use pre-computed lookup if available\n if (line <= this.maxPrecomputedLine) {\n const disabled = this.lineDisabledCodes.get(line);\n return !disabled || !disabled.has(code);\n }\n\n // Fall back to range checking\n for (const range of this.disabledRanges) {\n const endLine = range.endLine === -1 ? Infinity : range.endLine;\n if (line >= range.startLine && line <= endLine && range.code === code) {\n return false;\n }\n }\n\n return true;\n }\n\n /**\n * Check if a specific diagnostic code is enabled at a node's position\n */\n isCodeEnabledAtNode(code: ErrorCodes.CodeTypes, node: SyntaxNode): boolean {\n return this.isCodeEnabledAtLine(code, node.startPosition.row);\n }\n\n /**\n * Get all disabled codes at a specific line (for debugging)\n */\n getDisabledCodesAtLine(line: number): ErrorCodes.CodeTypes[] {\n if (line <= this.maxPrecomputedLine) {\n const codes = this.lineDisabledCodes.get(line);\n return codes ? Array.from(codes) : [];\n }\n\n const disabled: ErrorCodes.CodeTypes[] = [];\n for (const range of this.disabledRanges) {\n const endLine = range.endLine === -1 ? Infinity : range.endLine;\n if (line >= range.startLine && line <= endLine) {\n disabled.push(range.code);\n }\n }\n\n return [...new Set(disabled)];\n }\n\n /**\n * Get summary information about the computed ranges\n */\n getSummary(): {\n totalRanges: number;\n precomputedLines: number;\n linesWithDisabledCodes: number;\n } {\n return {\n totalRanges: this.disabledRanges.length,\n precomputedLines: this.maxPrecomputedLine + 1,\n linesWithDisabledCodes: this.lineDisabledCodes.size,\n };\n }\n\n /**\n * Debug: Get detailed state at a specific line\n */\n getLineState(line: number): {\n line: number;\n disabledCodes: ErrorCodes.CodeTypes[];\n enabledCodes: ErrorCodes.CodeTypes[];\n } {\n const disabledCodes = this.getDisabledCodesAtLine(line);\n const disabledSet = new Set(disabledCodes);\n const enabledCodes = Array.from(this.globalEnabledCodes).filter(c => !disabledSet.has(c));\n\n return {\n line,\n disabledCodes,\n enabledCodes,\n };\n }\n}\n\n/**\n * Convenience function to create a DiagnosticRangeChecker from a syntax tree\n */\nexport function createDiagnosticChecker(root: SyntaxNode, maxLine: number): {\n checker: DiagnosticRangeChecker;\n result: DiagnosticRangesResult;\n} {\n const result = computeDiagnosticRanges(root, maxLine);\n const checker = new DiagnosticRangeChecker(result, maxLine);\n return { checker, result };\n}\n"
},
{
"path": "src/diagnostics/error-codes.ts",
"content": "import { CodeDescription, DiagnosticSeverity } from 'vscode-languageserver';\n\nexport namespace ErrorCodes {\n\n export const missingEnd = 1001;\n export const extraEnd = 1002;\n export const zeroIndexedArray = 1003;\n export const sourceFileDoesNotExist = 1004;\n export const dotSourceCommand = 1005;\n\n export const singleQuoteVariableExpansion = 2001;\n export const usedWrapperFunction = 2002;\n export const usedUnviersalDefinition = 2003;\n export const usedExternalShellCommandWhenBuiltinExists = 2004;\n\n export const testCommandMissingStringCharacters = 3001;\n export const missingQuietOption = 3002;\n export const dereferencedDefinition = 3003;\n\n export const autoloadedFunctionMissingDefinition = 4001;\n export const autoloadedFunctionFilenameMismatch = 4002;\n export const functionNameUsingReservedKeyword = 4003;\n export const unusedLocalDefinition = 4004;\n export const autoloadedCompletionMissingCommandName = 4005;\n export const duplicateFunctionDefinitionInSameScope = 4006;\n export const autoloadedFunctionWithEventHookUnused = 4007;\n export const requireAutloadedFunctionHasDescription = 4008;\n\n export const argparseMissingEndStdin = 5001;\n export const unreachableCode = 5555;\n\n export const fishLspDeprecatedEnvName = 6001;\n\n export const unknownCommand = 7001;\n\n export const invalidDiagnosticCode = 8001;\n\n export const syntaxError = 9999;\n\n export type CodeTypes =\n 1001 | 1002 | 1003 | 1004 | 1005 |\n 2001 | 2002 | 2003 | 2004 |\n 3001 | 3002 | 3003 |\n 4001 | 4002 | 4003 | 4004 | 4005 | 4006 | 4007 | 4008 |\n 5001 | 5555 |\n 6001 |\n 7001 |\n 8001 |\n 9999;\n\n export type CodeValueType = {\n severity: DiagnosticSeverity;\n code: CodeTypes;\n codeDescription: CodeDescription;\n source: 'fish-lsp';\n isDeprecated?: boolean;\n message: string;\n };\n\n export type DiagnosticCode = {\n [k in CodeTypes]: CodeValueType;\n };\n\n export const codes: { [k in CodeTypes]: CodeValueType } = {\n [missingEnd]: {\n severity: DiagnosticSeverity.Error,\n code: missingEnd,\n codeDescription: { href: 'https://fishshell.com/docs/current/cmds/end.html' },\n source: 'fish-lsp',\n message: 'missing closing token',\n },\n [extraEnd]: {\n severity: DiagnosticSeverity.Error,\n code: extraEnd,\n codeDescription: { href: 'https://fishshell.com/docs/current/cmds/end.html' },\n source: 'fish-lsp',\n message: 'extra closing token',\n },\n [zeroIndexedArray]: {\n severity: DiagnosticSeverity.Error,\n code: zeroIndexedArray,\n codeDescription: { href: 'https://fishshell.com/docs/current/language.html#slices' },\n source: 'fish-lsp',\n message: 'invalid array index',\n },\n [sourceFileDoesNotExist]: {\n severity: DiagnosticSeverity.Error,\n code: sourceFileDoesNotExist,\n codeDescription: { href: 'https://fishshell.com/docs/current/cmds/source.html' },\n source: 'fish-lsp',\n message: 'source filename does not exist',\n },\n [dotSourceCommand]: {\n severity: DiagnosticSeverity.Error,\n code: dotSourceCommand,\n codeDescription: { href: 'https://fishshell.com/docs/current/cmds/source.html' },\n source: 'fish-lsp',\n message: '`.` source command not allowed, use `source` instead',\n },\n /** consider disabling this */\n [singleQuoteVariableExpansion]: {\n severity: DiagnosticSeverity.Warning,\n code: singleQuoteVariableExpansion,\n codeDescription: { href: 'https://fishshell.com/docs/current/language.html#variable-expansion' },\n source: 'fish-lsp',\n isDeprecated: true,\n message: 'non-escaped expansion variable in single quote string',\n },\n [usedWrapperFunction]: {\n severity: DiagnosticSeverity.Warning,\n code: usedWrapperFunction,\n codeDescription: { href: 'https://fishshell.com/docs/current/commands.html' },\n source: 'fish-lsp',\n message: 'Wrapper command (`export`, `alias`, etc.) used, while preferring usage of primitive commands.\\n\\nUse command: \\n```fish\\nset -gx fish_lsp_allow_fish_wrapper_functions true\\n```\\nto disable this warning globally.',\n },\n [usedUnviersalDefinition]: {\n severity: DiagnosticSeverity.Warning,\n code: usedUnviersalDefinition,\n codeDescription: { href: 'https://fishshell.com/docs/current/language.html#universal-variables' },\n source: 'fish-lsp',\n message: 'Universal scope set in non-interactive session',\n },\n [usedExternalShellCommandWhenBuiltinExists]: {\n severity: DiagnosticSeverity.Warning,\n code: usedExternalShellCommandWhenBuiltinExists,\n codeDescription: { href: 'https://fishshell.com/docs/current/cmds/builtins.html' },\n source: 'fish-lsp',\n message: 'External shell command used when equivalent fish builtin exists',\n },\n [testCommandMissingStringCharacters]: {\n severity: DiagnosticSeverity.Warning,\n code: testCommandMissingStringCharacters,\n codeDescription: { href: 'https://fishshell.com/docs/current/cmds/test.html#examples' },\n source: 'fish-lsp',\n message: 'test command string check, should be wrapped as a string',\n },\n [missingQuietOption]: {\n severity: DiagnosticSeverity.Warning,\n code: missingQuietOption,\n codeDescription: { href: 'https://fishshell.com/docs/current/search.html?q=-q' },\n source: 'fish-lsp',\n message: 'Conditional command should include a silence option',\n },\n [dereferencedDefinition]: {\n severity: DiagnosticSeverity.Warning,\n code: dereferencedDefinition,\n codeDescription: { href: 'https://fishshell.com/docs/current/language.html#dereferencing-variables' },\n source: 'fish-lsp',\n message: 'Dereferenced variable could be undefined',\n },\n [autoloadedFunctionMissingDefinition]: {\n severity: DiagnosticSeverity.Warning,\n code: autoloadedFunctionMissingDefinition,\n codeDescription: { href: 'https://fishshell.com/docs/current/cmds/functions.html' },\n source: 'fish-lsp',\n message: 'Autoloaded function missing definition',\n },\n [autoloadedFunctionFilenameMismatch]: {\n severity: DiagnosticSeverity.Error,\n code: autoloadedFunctionFilenameMismatch,\n codeDescription: { href: 'https://fishshell.com/docs/current/cmds/functions.html' },\n source: 'fish-lsp',\n message: 'Autoloaded filename does not match function name',\n },\n [functionNameUsingReservedKeyword]: {\n severity: DiagnosticSeverity.Error,\n code: functionNameUsingReservedKeyword,\n codeDescription: { href: 'https://fishshell.com/docs/current/cmds/functions.html' },\n source: 'fish-lsp',\n message: 'Function name uses reserved keyword',\n },\n [unusedLocalDefinition]: {\n severity: DiagnosticSeverity.Warning,\n code: unusedLocalDefinition,\n codeDescription: { href: 'https://fishshell.com/docs/current/language.html#local-variables' },\n source: 'fish-lsp',\n message: 'Unused local',\n },\n [autoloadedCompletionMissingCommandName]: {\n severity: DiagnosticSeverity.Error,\n code: autoloadedCompletionMissingCommandName,\n codeDescription: { href: 'https://fishshell.com/docs/current/cmds/complete.html' },\n source: 'fish-lsp',\n message: 'Autoloaded completion missing command name',\n },\n [duplicateFunctionDefinitionInSameScope]: {\n severity: DiagnosticSeverity.Warning,\n code: duplicateFunctionDefinitionInSameScope,\n codeDescription: { href: 'https://fishshell.com/docs/current/cmds/functions.html' },\n source: 'fish-lsp',\n message: 'Duplicate function definition exists in the same scope.\\n\\nAmbiguous function',\n },\n [autoloadedFunctionWithEventHookUnused]: {\n severity: DiagnosticSeverity.Warning,\n code: autoloadedFunctionWithEventHookUnused,\n codeDescription: { href: 'https://fishshell.com/docs/current/language.html#event' },\n source: 'fish-lsp',\n message: 'Autoloaded function with event hook is unused',\n },\n [requireAutloadedFunctionHasDescription]: {\n severity: DiagnosticSeverity.Warning,\n code: requireAutloadedFunctionHasDescription,\n codeDescription: { href: 'https://fishshell.com/docs/current/cmds/functions.html' },\n source: 'fish-lsp',\n message: 'Autoloaded function requires a description | Add `-d`/`--description` to the function definition',\n },\n [argparseMissingEndStdin]: {\n severity: DiagnosticSeverity.Error,\n code: argparseMissingEndStdin,\n codeDescription: { href: 'https://fishshell.com/docs/current/cmds/argparse.html' },\n source: 'fish-lsp',\n message: 'argparse missing end of stdin',\n },\n [unreachableCode]: {\n severity: DiagnosticSeverity.Warning,\n code: unreachableCode,\n codeDescription: { href: 'https://fishshell.com/docs/current/language.html#unreachable-code-blocks' },\n source: 'fish-lsp',\n message: 'Unreachable code blocks detected',\n },\n [fishLspDeprecatedEnvName]: {\n severity: DiagnosticSeverity.Warning,\n code: fishLspDeprecatedEnvName,\n codeDescription: { href: 'https://github.com/ndonfris/fish-lsp#environment-variables' },\n source: 'fish-lsp',\n message: 'Deprecated fish-lsp environment variable name',\n },\n [unknownCommand]: {\n severity: DiagnosticSeverity.Warning,\n code: unknownCommand,\n codeDescription: { href: 'https://fishshell.com/docs/current/language.html#commands' },\n source: 'fish-lsp',\n message: 'Unknown command',\n },\n [invalidDiagnosticCode]: {\n severity: DiagnosticSeverity.Warning,\n code: invalidDiagnosticCode,\n codeDescription: { href: 'https://github.com/ndonfris/fish-lsp/wiki/Diagnostic-Error-Codes' },\n source: 'fish-lsp',\n message: 'Invalid diagnostic control code',\n },\n [syntaxError]: {\n severity: DiagnosticSeverity.Error,\n code: syntaxError,\n codeDescription: { href: 'https://fishshell.com/docs/current/fish_for_bash_users.html#syntax-overview' },\n source: 'fish-lsp',\n message: 'fish syntax error',\n },\n };\n\n /** All error codes */\n export const allErrorCodes = Object.values(codes).map((diagnostic) => diagnostic.code) as CodeTypes[];\n\n export const allErrorCodeObjects = Object.values(codes) as CodeValueType[];\n\n export const nonDeprecatedErrorCodes = allErrorCodeObjects.filter((code) => !code.isDeprecated);\n\n export function getSeverityString(severity: DiagnosticSeverity | undefined): string {\n if (!severity) return '';\n switch (severity) {\n case DiagnosticSeverity.Error:\n return 'Error';\n case DiagnosticSeverity.Warning:\n return 'Warning';\n case DiagnosticSeverity.Information:\n return 'Information';\n case DiagnosticSeverity.Hint:\n return 'Hint';\n default:\n return '';\n }\n }\n\n export function codeTypeGuard(code: CodeTypes | number | string | undefined): code is CodeTypes {\n return typeof code === 'number' && code >= 1000 && code < 10000 && allErrorCodes.includes(code as CodeTypes);\n }\n\n export function getDiagnostic(code: CodeTypes | number): CodeValueType {\n if (typeof code === 'number') return codes[code as CodeTypes];\n return codes[code];\n }\n}\n"
},
{
"path": "src/diagnostics/invalid-error-code.ts",
"content": "import { Diagnostic } from 'vscode-languageserver';\nimport { SyntaxNode } from 'web-tree-sitter';\nimport { ErrorCodes } from './error-codes';\nimport { isComment } from '../utils/node-types';\nimport { logger } from '../logger';\nimport { FishDiagnostic } from './types';\n\n// More precise regex to capture exact positions of code numbers\nconst DIAGNOSTIC_COMMENT_REGEX = /^#\\s*@fish-lsp-(disable|enable)(?:-(next-line))?\\s/;\n\nexport function isPossibleDiagnosticComment(node: SyntaxNode): boolean {\n if (!isComment(node)) return false;\n return DIAGNOSTIC_COMMENT_REGEX.test(node.text.trim());\n}\n\n// Function to find codes with their positions\nfunction findCodes(text: string): { code: string; startIndex: number; }[] {\n // Find where the codes section starts (after the directive)\n const directiveMatch = text.match(/@fish-lsp-(?:disable|enable)(?:-next-line)?/); // remove leading comment\n if (!directiveMatch) return [];\n\n const codesStart = directiveMatch.index! + directiveMatch[0].length;\n const codesSection = text.slice(codesStart);\n\n // Find all code tokens in the codes section\n const result: { code: string; startIndex: number; }[] = [];\n const codeRegex = /(\\d+)/g;\n let match;\n\n while ((match = codeRegex.exec(codesSection)) !== null) {\n result.push({\n code: match[0],\n startIndex: codesStart + match.index,\n });\n }\n\n logger.log('Found codes:', result, 'on text:', text);\n logger.log('Directive:', directiveMatch);\n return result;\n}\n\nexport function detectInvalidDiagnosticCodes(node: SyntaxNode): Diagnostic[] {\n // Early return if not a diagnostic comment\n if (!isComment(node)) return [];\n\n const text = node.text.trim();\n if (!DIAGNOSTIC_COMMENT_REGEX.test(text)) return [];\n\n // Find all code numbers with their positions\n const codePositions = findCodes(text);\n const diagnostics: Diagnostic[] = [];\n\n for (const { code, startIndex } of codePositions) {\n const codeNum = parseInt(code, 10);\n\n // Check if it's a valid error code\n if (isNaN(codeNum) || !ErrorCodes.codeTypeGuard(codeNum)) {\n // Create diagnostic for this invalid code\n const diagnostic = FishDiagnostic.create(ErrorCodes.invalidDiagnosticCode, node, `Invalid diagnostic code: '${code}'. Valid codes are: ${ErrorCodes.allErrorCodes.map(c => c.toString()).join(', ')}.`);\n diagnostic.range = {\n start: {\n line: node.startPosition.row,\n character: node.startPosition.column + startIndex,\n },\n end: {\n line: node.startPosition.row,\n character: node.startPosition.column + startIndex + code.length,\n },\n };\n diagnostics.push(diagnostic);\n }\n }\n\n return diagnostics;\n}\n\n// Function to add to the validate.ts getDiagnostics function\nexport function checkForInvalidDiagnosticCodes(node: SyntaxNode): Diagnostic[] {\n if (isPossibleDiagnosticComment(node)) {\n return detectInvalidDiagnosticCodes(node);\n }\n return [];\n}\n"
},
{
"path": "src/diagnostics/missing-completions.ts",
"content": "import { Diagnostic, Location } from 'vscode-languageserver';\nimport { analyzer } from '../analyze';\nimport { LspDocument } from '../document';\nimport { logger } from '../logger';\nimport { FishSymbol } from '../parsing/symbol';\nimport { getRange } from '../utils/tree-sitter';\nimport { CompletionSymbol, getGroupedCompletionSymbolsAsArgparse, groupCompletionSymbolsTogether } from '../parsing/complete';\nimport { flattenNested } from '../utils/flatten';\nimport * as Locations from '../utils/locations';\nimport { uriToReadablePath } from '../utils/translation';\nimport { equalDiagnostics } from '../code-actions/code-action-handler';\n\n// TODO: add this to the validation.ts file\n\nexport function findAllMissingArgparseFlags(\n document: LspDocument,\n) {\n const fishSymbols: FishSymbol[] = [];\n const completionSymbols: CompletionSymbol[][] = [];\n const diagnostics: Diagnostic[] = [];\n if (document.isFunction()) {\n const result = findMissingArgparseFlagsWithExistingCompletions(document);\n completionSymbols.push(...result);\n }\n if (document.isAutoloadedWithPotentialCompletions()) {\n const result = findMissingCompletionsWithExistingArgparse(document);\n fishSymbols.push(...result);\n }\n\n if (completionSymbols.length === 0 && fishSymbols.length === 0) {\n logger.debug(`No missing argparse flags found in document: ${document.uri}`);\n return [];\n }\n\n // create diagnostics for missing completions\n if (completionSymbols.length > 0) {\n for (const completionGroup of completionSymbols) {\n const diag = createCompletionDiagnostic(completionGroup, analyzer.getFlatDocumentSymbols(document.uri));\n if (diag) {\n const toAdd = diag.filter(d => !diagnostics.some(existing => equalDiagnostics(existing, d)));\n diagnostics.push(...toAdd);\n }\n }\n }\n\n // create diagnostics for missing argparse flags\n if (fishSymbols.length > 0) {\n for (const symbol of fishSymbols) {\n const diag = createArgparseDiagnostic(symbol, document);\n if (diag) {\n const toAdd = diag.filter(d => !diagnostics.some(existing => equalDiagnostics(existing, d)));\n diagnostics.push(...toAdd);\n }\n }\n }\n\n // Check if the symbol is a command definition\n return diagnostics;\n}\n\nfunction findMissingArgparseFlagsWithExistingCompletions(\n document: LspDocument,\n): CompletionSymbol[][] {\n const missingCompletions: CompletionSymbol[][] = [];\n\n /**\n * Retrieve all global function symbols in the document.\n */\n const symbols = analyzer.getFlatDocumentSymbols(document.uri);\n const globalSymbols = symbols.filter(s => s.isGlobal() && s.isFunction());\n\n /**\n * Flatten all global autoloaded function symbols,\n * and extract their argparse symbols.\n */\n const argparseSymbols = flattenNested(...globalSymbols).filter(s => s.fishKind === 'ARGPARSE');\n for (const symbol of argparseSymbols) {\n // get the locations where the completion symbol is implemented\n const completionLocations = analyzer.getImplementation(document, symbol.toPosition())\n .filter(loc => !symbol.equalsLocation(loc));\n\n if (completionLocations.length === 0) continue;\n\n for (const location of completionLocations) {\n const cSymbols = analyzer\n .getFlatCompletionSymbols(location.uri)\n .filter(s => s.isNonEmpty());\n\n if (cSymbols.length === 0) continue;\n\n const grouped = groupCompletionSymbolsTogether(...cSymbols);\n const result = getGroupedCompletionSymbolsAsArgparse(grouped, argparseSymbols);\n if (result.length > 0) {\n missingCompletions.push(...result);\n }\n }\n }\n return missingCompletions;\n}\n\nfunction findMissingCompletionsWithExistingArgparse(\n document: LspDocument,\n) {\n const missingCompletions: FishSymbol[] = [];\n\n const completionSymbols = analyzer.getFlatCompletionSymbols(document.uri).filter(s => s.isNonEmpty());\n const implementationLocations: Location[] = [];\n\n completionSymbols.forEach(s => {\n const pos = s.toPosition();\n if (!pos) return;\n const results = analyzer.getImplementation(document, pos)\n .filter(loc => !Locations.Location.equals(loc, s.toLocation()));\n if (results.length === 0) return;\n implementationLocations.push(...results);\n });\n\n const grouped = groupCompletionSymbolsTogether(...completionSymbols);\n\n if (grouped.length === 0) return missingCompletions;\n\n for (const location of implementationLocations) {\n const cSymbols = analyzer.getFlatDocumentSymbols(location.uri)\n .filter(s => s.fishKind === 'ARGPARSE');\n\n if (cSymbols.length === 0) continue;\n\n for (const symbol of cSymbols) {\n if (grouped.some(group => group.some(s => s.equalsArgparse(symbol)))) {\n // If the symbol is already in the grouped completions, skip it\n continue;\n }\n missingCompletions.push(symbol);\n }\n }\n return missingCompletions;\n}\n\nfunction createCompletionDiagnostic(completionGroup: CompletionSymbol[], symbols: FishSymbol[]) {\n const diagnostics: Diagnostic[] = [];\n const focusedSymbol = symbols.find(s => s.isFunction() && s.isGlobal() && completionGroup.every(c => c.commandName === s.name));\n if (!focusedSymbol) {\n logger.warning(`No focused location found for completion group: ${completionGroup.map(c => c.text).join(', ')}`, 'HERE');\n return null;\n }\n\n const hasArgparse = flattenNested(focusedSymbol).find(l => l.fishKind === 'ARGPARSE');\n const focusedNode = hasArgparse ? hasArgparse.node.firstNamedChild : focusedSymbol.node.firstChild?.nextSibling;\n if (!focusedNode) {\n logger.warning(`No focused node found for completion group: ${completionGroup.map(c => c.text).join(', ')}`);\n return null;\n }\n\n const joinedGroup = completionGroup.map(c => c.toArgparseOpt()).join('/');\n\n const firstCompletion = completionGroup.find(c => c.isNonEmpty())!;\n const firstCompletionDoc = firstCompletion.document!;\n const prettyPath = uriToReadablePath(firstCompletionDoc.uri);\n\n // Create a diagnostic for the completion group\n diagnostics.push({\n message: `Add missing \\`argparse ${joinedGroup}\\` from completion in '${prettyPath}'`,\n severity: 1, // Warning\n source: 'fish-lsp',\n code: 4008,\n range: getRange(focusedNode),\n data: {\n node: focusedNode,\n },\n });\n\n const joinedGroupUsage = completionGroup.map((item, idx) => {\n if (idx === 0) {\n return item.toUsage();\n }\n return item.toFlag();\n }).join('/');\n diagnostics.push({\n message: `Remove the unused completion \\`${joinedGroupUsage}\\` in '${prettyPath}'`,\n severity: 1, // Error\n source: 'fish-lsp',\n code: 4009,\n range: getRange(firstCompletion.parent),\n data: {\n node: firstCompletion.parent,\n },\n });\n\n return diagnostics;\n}\n\nfunction createArgparseDiagnostic(\n symbol: FishSymbol,\n document: LspDocument,\n): Diagnostic[] {\n const diagnostics: Diagnostic[] = [];\n const focusedNode = symbol.focusedNode;\n\n if (!focusedNode) {\n logger.warning(`No focused node found for symbol: ${symbol.name}`);\n return [];\n }\n\n const prettyPath = uriToReadablePath(document.uri);\n diagnostics.push({\n message: `remove unused \\`argparse ${symbol.argparseFlagName}\\` in '${prettyPath}'`,\n severity: 1, // Warning\n source: 'fish-lsp',\n code: 4009,\n range: getRange(focusedNode),\n data: {\n type: 'argparse removal',\n node: focusedNode,\n },\n });\n\n const completionLocation = analyzer.getImplementation(document, symbol.toPosition())\n .find(loc => !Locations.Location.equals(loc, symbol.toLocation()));\n\n if (completionLocation) {\n const prettyCompletionPath = uriToReadablePath(completionLocation.uri);\n diagnostics.push({\n message: `Add missing \\`${symbol.parent!.name + ' ' + symbol.argparseFlag}\\` completion in '${prettyCompletionPath}'`,\n severity: 1, // Warning\n source: 'fish-lsp',\n code: 4008,\n range: getRange(focusedNode),\n data: {\n type: 'argparse addition',\n node: focusedNode,\n },\n });\n }\n return diagnostics;\n}\n"
},
{
"path": "src/diagnostics/no-execute-diagnostic.ts",
"content": "// import { spawnSync } from 'child_process';\nimport { LspDocument } from '../document';\nimport { Diagnostic, DiagnosticSeverity } from 'vscode-languageserver';\nimport { logger } from '../logger';\nimport { execFishNoExecute } from '../utils/exec';\nimport { ErrorCodes } from './error-codes';\n\n/**\n * A unique diagnostic code to identify issues found by the no-execute diagnostic\n */\nconst NoExecuteErrorCode = ErrorCodes.syntaxError;\n\n/**\n * Parse the output from `fish --no-execute` on a script to identify syntax errors\n * @param document The document to run the no-execute check on\n * @param testMode If true, returns detailed output for testing purposes\n * @returns Array of diagnostics or detailed output if in test mode\n */\nexport function runNoExecuteDiagnostic(document: LspDocument): Diagnostic[] {\n try {\n // Get document content\n const scriptContent = document.getText();\n\n // Skip empty documents\n if (!scriptContent.trim()) {\n return [];\n }\n\n const result = execFishNoExecute(document.getFilePath()!);\n\n // Process the output and error\n if (result) {\n logger.log(`Fish --no-execute found output: ${result}`);\n return fishOutputToDiagnostics(result, document);\n // return parseNoExecuteOutput(result, document);\n }\n\n return [];\n } catch (error) {\n // Log the error but don't throw it\n logger.log(`Error in no-execute diagnostic: ${error}`);\n return [];\n }\n}\n\n/**\n * The main function to be called from validate.ts\n */\nexport function getNoExecuteDiagnostics(document: LspDocument): Diagnostic[] {\n // Only run on .fish files\n if (!document.uri.endsWith('.fish')) {\n return [];\n }\n\n const diagnostics = runNoExecuteDiagnostic(document);\n logger.log(`No-execute diagnostics for ${document.uri}: ${diagnostics.length} issues found`);\n return diagnostics;\n}\n\n/**\n * Parse fish errors from Fish output for a given document.\n *\n * @param document The document to whose contents errors refer\n * @param output The error output from Fish.\n * @return An array of all diagnostics\n */\nconst fishOutputToDiagnostics = (\n output: string,\n document: LspDocument,\n): Diagnostic[] => {\n const diagnostics: Array = [];\n const matches = getMatches(/^(.+) \\(line (\\d+)\\): (.+)$/gm, output);\n for (const match of matches) {\n const lineNumber = Number.parseInt(match[2]!);\n const message = match[3];\n\n const range = document.getLineRange(lineNumber - 1);\n const diagnostic = {\n severity: DiagnosticSeverity.Error,\n range,\n message: `Fish syntax error: ${message}`,\n source: 'fish-lsp',\n code: NoExecuteErrorCode,\n data: { isNoExecute: true, output },\n };\n diagnostics.push(diagnostic);\n }\n return diagnostics;\n};\n\n/**\n * Exec pattern against the given text and return an array of all matches.\n *\n * @param pattern The pattern to match against\n * @param text The text to match the pattern against\n * @return All matches of pattern in text.\n */\nconst getMatches = (\n pattern: RegExp,\n text: string,\n): ReadonlyArray => {\n const results = [];\n // We need to loop through the regexp here, so a let is required\n let match = pattern.exec(text);\n while (match !== null) {\n results.push(match);\n match = pattern.exec(text);\n }\n return results;\n};\n"
},
{
"path": "src/diagnostics/node-types.ts",
"content": "import Parser, { SyntaxNode } from 'web-tree-sitter';\nimport { findParentCommand, hasParent, isCommand, isCommandName, isCommandWithName, isEndStdinCharacter, isFunctionDefinitionName, isIfOrElseIfConditional, isMatchingOption, isOption, isString, isVariableDefinitionName } from '../utils/node-types';\nimport { getChildNodes, getRange, isNodeWithinOtherNode, precedesRange, TreeWalker } from '../utils/tree-sitter';\nimport { Maybe } from '../utils/maybe';\nimport { Option } from '../parsing/options';\nimport { isExistingSourceFilenameNode, isSourceCommandArgumentName } from '../parsing/source';\nimport { LspDocument } from '../document';\nimport { DiagnosticCommentsHandler } from './comments-handler';\nimport { FishSymbol } from '../parsing/symbol';\nimport { ErrorCodes } from './error-codes';\nimport { getReferences } from '../references';\nimport { config, Config } from '../config';\nimport { isBuiltin } from '../utils/builtins';\nimport { server } from '../server';\nimport { analyzer } from '../analyze';\nimport { FishCompletionItemKind } from '../utils/completion/types';\n\ntype startTokenType = 'function' | 'while' | 'if' | 'for' | 'begin' | 'switch' | '[' | '{' | '(' | \"'\" | '\"';\ntype endTokenType = 'end' | \"'\" | '\"' | ']' | '}' | ')';\n\nexport const ErrorNodeTypes: { [start in startTokenType]: endTokenType } = {\n ['function']: 'end',\n ['while']: 'end',\n ['for']: 'end',\n ['begin']: 'end',\n ['if']: 'end',\n ['switch']: 'end',\n ['\"']: '\"',\n [\"'\"]: \"'\",\n ['{']: '}',\n ['[']: ']',\n ['(']: ')',\n} as const;\n\nfunction isStartTokenType(str: string): str is startTokenType {\n return ['function', 'while', 'for', 'if', 'switch', 'begin', '[', '{', '(', \"'\", '\"'].includes(str);\n}\n\nexport function findErrorCause(children: Parser.SyntaxNode[]): Parser.SyntaxNode | null {\n const stack: Array<{ node: Parser.SyntaxNode; type: endTokenType; index: number; }> = [];\n\n for (let i = 0; i < children.length; i++) {\n const node = children[i];\n if (!node) continue;\n if (isStartTokenType(node.type)) {\n const expectedEndToken = ErrorNodeTypes[node.type];\n const matchIndex = stack.findIndex(item => item.type === expectedEndToken);\n\n if (matchIndex !== -1) {\n stack.splice(matchIndex, 1); // Remove the matched end token\n } else {\n stack.push({ node, type: expectedEndToken, index: i }); // Push the current node and expected end token to the stack\n }\n } else if (Object.values(ErrorNodeTypes).includes(node.type as endTokenType)) {\n stack.push({ node, type: node.type as endTokenType, index: i }); // Track all end tokens\n }\n }\n\n // Lookahead logic for unclosed quote tokens\n if (stack.length > 0) {\n for (const item of stack) {\n // Check if this is a quote token (' or \")\n if (item.node.type === \"'\" || item.node.type === '\"') {\n // Look ahead to see if there are nodes after this quote that suggest it should be closed\n const nodesAfterQuote = children.slice(item.index + 1);\n if (hasContentAfterQuote(nodesAfterQuote)) {\n return item.node; // Return this unclosed quote as the error cause\n }\n }\n }\n }\n\n // Return the first unmatched start token from the stack, if any\n return stack.length > 0 ? stack[0]?.node || null : null;\n}\n\nfunction hasContentAfterQuote(nodes: Parser.SyntaxNode[]): boolean {\n // Check if there are meaningful nodes after the quote that suggest it should be closed\n for (const node of nodes) {\n // Skip whitespace and other non-meaningful nodes\n if (node.type === 'escape_sequence' ||\n node.type === 'word' ||\n node.text.trim().length > 0) {\n return true;\n }\n }\n return false;\n}\n\nexport function isExtraEnd(node: SyntaxNode) {\n return node.type === 'command' && node.text === 'end';\n}\n\nexport function isZeroIndex(node: SyntaxNode) {\n return node.type === 'index' && node.text === '0';\n}\n\nexport function isSingleQuoteVariableExpansion(node: Parser.SyntaxNode): boolean {\n if (node.type !== 'single_quote_string') {\n return false;\n }\n if (node.parent && isCommandWithName(node.parent, 'string')) {\n return false;\n }\n\n const variableRegex = /(? !isOption(c) && isVariableDefinitionName(c));\n\n if (!definitionName || !precedesRange(getRange(node), getRange(definitionName))) {\n return false;\n }\n // check if the command is a -U/--universal option\n return isMatchingOption(node, Option.create('-U', '--universal'));\n }\n return false;\n}\n\nexport function isSourceFilename(node: SyntaxNode): boolean {\n if (isSourceCommandArgumentName(node)) {\n const isExisting = isExistingSourceFilenameNode(node);\n if (!isExisting) {\n // check if the node is a variable expansion\n // if it is, do not through a diagnostic because we can't evaluate if this is a valid path\n // An example of this case:\n // for file in $__fish_data_dir/functions\n // source $file # <--- we have no clue if this file exists\n // end\n if (node.type === 'variable_expansion') {\n return false;\n }\n // also skip something like `source '$file'`\n if (isString(node)) {\n return false;\n }\n // remove `source (some_cmd a b c d)`\n if (hasParent(node, (n) => n.type === 'command_substitution')) {\n return false;\n }\n // remove `source /path/with/wildcards/*/file.fish`\n if (node.text.includes('*') || node.text.includes('?')) {\n return false;\n }\n return true;\n }\n return !isExisting;\n }\n return false;\n}\n\nexport function isDotSourceCommand(node: SyntaxNode): boolean {\n if (node.parent && isCommandWithName(node.parent, '.')) {\n return node.parent.firstNamedChild?.equals(node) || false;\n }\n return false;\n}\n\nexport function isTestCommandVariableExpansionWithoutString(node: SyntaxNode): boolean {\n const parent = node.parent;\n const previousSibling = node.previousSibling;\n if (!parent || !previousSibling) return false;\n\n if (!isCommandWithName(parent, 'test', '[')) return false;\n\n if (isMatchingOption(previousSibling, Option.short('-n'), Option.short('-z'))) {\n return !isString(node) && !!parent.child(2) && parent.child(2)!.equals(node);\n }\n\n return false;\n}\n\nfunction isInsideStatementCondition(statement: SyntaxNode, node: SyntaxNode): boolean {\n const conditionNode = statement.childForFieldName('condition');\n if (!conditionNode) return false;\n return isNodeWithinOtherNode(node, conditionNode);\n}\n\n/**\n * util for collecting if conditional_statement commands\n * Necessary because there is two types of conditional statements:\n * 1.) if cmd_1 || cmd_2; ...; end;\n * 2.) if cmd_1; or cmd_2; ...; end;\n * Case two is handled by the if statement, checking for the parent type of conditional_execution\n * @param node - the current node to check (should be a command)\n * @returns true if the node is a conditional statement, otherwise false\n */\nexport function isConditionalStatement(node: SyntaxNode) {\n if (!node.isNamed) return false;\n if (['\\n', ';'].includes(node?.previousSibling?.type || '')) return false;\n let curr: SyntaxNode | null = node.parent;\n while (curr) {\n if (curr.type === 'conditional_execution') {\n curr = curr?.parent;\n } else if (isIfOrElseIfConditional(curr)) {\n return isInsideStatementCondition(curr, node);\n } else {\n break;\n }\n }\n return false;\n}\n\n/**\n * Checks if a command has a command substitution. For example,\n *\n * ```fish\n * if set -l fishdir (status fish-path | string match -vr /bin/)\n * echo $fishdir\n * end\n * ```\n *\n * @param node - the current node to check (should be a `set` command)\n * @returns true if the command has a command substitution, otherwise false\n */\nfunction hasCommandSubstitution(node: SyntaxNode) {\n return node.childrenForFieldName('argument').filter(c => c.type === 'command_substitution').length > 0;\n}\n\n/**\n * Get all conditional command names based on the config setting\n * FIX: https://github.com/ndonfris/fish-lsp/issues/93\n */\nconst allConditionalCommandNames = ['command', 'type', 'set', 'string', 'abbr', 'builtin', 'functions', 'jobs'];\nconst getConditionalCommandNames = () => {\n if (!config.fish_lsp_strict_conditional_command_warnings) {\n return ['set', 'abbr', 'functions', 'jobs'];\n }\n return allConditionalCommandNames;\n};\n\n/**\n * Command analysis utilities for functional composition\n * Provides reusable command analysis operations for conditional execution logic\n */\nclass CommandAnalyzer {\n /**\n * Find the first command in a node's children\n */\n static findFirstCommand(node: SyntaxNode): Maybe {\n return TreeWalker.findFirstChild(node, isCommand);\n }\n\n /**\n * Check if a command has quiet flags (-q, --quiet, --query)\n */\n static hasQuietFlags(command: SyntaxNode): boolean {\n return command.childrenForFieldName('argument')\n .some(arg =>\n isMatchingOption(arg, Option.create('-q', '--quiet')) ||\n isMatchingOption(arg, Option.create('-q', '--query')),\n );\n }\n\n /**\n * Check if a command is in the list of conditional commands\n */\n static isConditionalCommand(command: SyntaxNode): boolean {\n return isCommandWithName(command, ...getConditionalCommandNames());\n }\n}\n\n/**\n * Conditional context analysis utilities\n * Provides methods to analyze conditional execution contexts\n */\nclass ConditionalContext {\n /**\n * Check if a node is at the top level (direct child of program)\n */\n static isTopLevel(node: SyntaxNode): boolean {\n return Maybe.of(node.parent)\n .map(parent => parent.type === 'program')\n .getOrElse(false);\n }\n\n /**\n * Check if a node is used as a condition in an if/else if statement\n */\n static isUsedAsCondition(node: SyntaxNode): boolean {\n return Maybe.of(node.parent)\n .filter(isIfOrElseIfConditional)\n .flatMap(parent => Maybe.of(parent.childForFieldName('condition')))\n .equals(node);\n }\n\n /**\n * Check if a node contains conditional operators (&&, ||)\n */\n static hasConditionalOperators(node: SyntaxNode): boolean {\n return node.text.includes('&&') || node.text.includes('||');\n }\n\n /**\n * Check if a node is a conditional chain node (conditional_execution or ERROR with operators)\n */\n static isConditionalChainNode(node: SyntaxNode): boolean {\n return node.type === 'conditional_execution' ||\n node.type === 'ERROR' && ConditionalContext.hasConditionalOperators(node);\n }\n}\n\n/**\n * Check if a command in a conditional context needs a -q/--quiet/--query flag\n *\n * This function identifies commands that are used as conditional expressions and\n * should have explicit quiet flags to suppress output when used for existence checking.\n *\n * Rules:\n * 1. In conditional_execution chains (&&, ||): only check the first command\n * 2. In if/else if conditions: check the first command in the condition\n * 3. Commands inside if body, nested if statements, etc. are not checked\n *\n * @param node - the command name node to check\n * @returns true if the command needs a quiet flag, false otherwise\n */\nexport function isConditionalWithoutQuietCommand(node: SyntaxNode): boolean {\n if (!config.fish_lsp_strict_conditional_command_warnings) {\n return false;\n }\n return Maybe.of(node)\n .filter(isCommandName)\n .map(n => n.parent)\n .filter(isCommand)\n .filter(CommandAnalyzer.isConditionalCommand)\n .filter(cmd => !isCommandWithName(cmd, 'set') || !hasCommandSubstitution(cmd))\n .filter(cmd => !CommandAnalyzer.hasQuietFlags(cmd))\n .map(cmd => isCommandInConditionalContext(cmd))\n .getOrElse(false);\n}\n\n/**\n * Determines if a command is in a conditional context where it should have quiet flags\n *\n * Two scenarios:\n * 1. Command is the first command in a conditional_execution chain (cmd1 && cmd2 || cmd3)\n * 2. Command is the first command in an if/else if condition (including nested ones)\n */\nfunction isCommandInConditionalContext(command: SyntaxNode): boolean {\n // Check if this is the first command in a conditional_execution chain\n if (isFirstCommandInConditionalChain(command)) {\n return true;\n }\n\n // Check if this is the first command in an if/else if condition (including nested)\n if (isFirstCommandInAnyIfCondition(command)) {\n return true;\n }\n\n return false;\n}\n\n/**\n * Check if a command is the first command in a conditional_execution chain that is used as a test\n * Examples: \"set a && set -q b\" at top level or in if condition - only \"set a\" should be flagged\n * But \"set a && set b\" inside an if body should NOT be flagged\n */\nfunction isFirstCommandInConditionalChain(command: SyntaxNode): boolean {\n return TreeWalker.findHighest(command, ConditionalContext.isConditionalChainNode)\n .filter(rootNode =>\n ConditionalContext.isTopLevel(rootNode) ||\n ConditionalContext.isUsedAsCondition(rootNode),\n )\n .flatMap(CommandAnalyzer.findFirstCommand)\n .equals(command);\n}\n\n/**\n * Check if a command is the first command in any if/else if condition (including nested)\n * Examples: \"if set a; end\" or \"else if set b; end\" or nested \"if set -q PATH; if set YARN_PATH; ...\"\n */\nfunction isFirstCommandInAnyIfCondition(command: SyntaxNode): boolean {\n return TreeWalker.walkUpAll(command, isIfOrElseIfConditional)\n .some(ifNode =>\n Maybe.of(ifNode.childForFieldName('condition'))\n .flatMap(condition => isFirstCommandInSpecificCondition(command, condition))\n .getOrElse(false),\n );\n}\n\n/**\n * Check if a command is the first command in a specific condition node\n */\nfunction isFirstCommandInSpecificCondition(command: SyntaxNode, conditionNode: SyntaxNode): Maybe {\n // Direct command match\n if (isCommand(conditionNode)) {\n return Maybe.of(conditionNode.equals(command));\n }\n\n // Find first command in condition\n return CommandAnalyzer.findFirstCommand(conditionNode)\n .map(firstCmd => firstCmd.equals(command));\n}\n\nexport function isVariableDefinitionWithExpansionCharacter(node: SyntaxNode, definedVariableExpansions: { [name: string]: SyntaxNode[]; } = {}): boolean {\n if (!isVariableDefinitionName(node)) return false;\n const parent = findParentCommand(node);\n if (parent && isCommandWithName(parent, 'set', 'read')) {\n if (!isVariableDefinitionName(node)) return false;\n const name = node.text.startsWith('$') ? node.text.slice(1) : node.text;\n if (!name || name.length === 0) return false;\n\n if (definedVariableExpansions[name] && definedVariableExpansions[name]?.some(scope => isNodeWithinOtherNode(node, scope))) {\n return false;\n }\n return node.type === 'variable_expansion' || node.text.startsWith('$');\n }\n\n return false;\n}\n\nexport type LocalFunctionCallType = {\n node: SyntaxNode;\n text: string;\n};\n\nexport function isMatchingCompleteOptionIsCommand(node: SyntaxNode) {\n return isMatchingOption(node, Option.create('-n', '--condition').withValue())\n || isMatchingOption(node, Option.create('-a', '--arguments').withValue())\n || isMatchingOption(node, Option.create('-c', '--command').withValue());\n}\n\nexport function isMatchingAbbrFunction(node: SyntaxNode) {\n return isMatchingOption(node, Option.create('-f', '--function').withValue());\n}\n\nexport function isAbbrDefinitionName(node: SyntaxNode) {\n const parent = findParentCommand(node);\n if (!parent) return false;\n if (!isCommandWithName(parent, 'abbr')) return false;\n const child = parent.childrenForFieldName('argument')\n .filter(n => !isOption(n))\n .find(n => n.type === 'word' && n.text !== '--' && !isString(n));\n\n return child ? child.equals(node) : false;\n}\n\nexport function isArgparseWithoutEndStdin(node: SyntaxNode) {\n if (!isCommandWithName(node, 'argparse')) return false;\n const endStdin = getChildNodes(node).find(n => isEndStdinCharacter(n));\n if (!endStdin) return true;\n return false;\n}\n\nexport function isPosixCommandInsteadOfFishCommand(node: SyntaxNode): boolean {\n if (!config.fish_lsp_prefer_builtin_fish_commands) return false;\n if (!isCommandName(node)) {\n return false;\n }\n const parent = findParentCommand(node);\n if (!parent) return false;\n\n if (isCommandWithName(parent, 'realpath')) {\n return !parent.children.some(c => isOption(c));\n }\n if (isCommandWithName(parent, 'dirname', 'basename')) {\n return true;\n }\n if (isCommandWithName(parent, 'cut', 'wc')) {\n return true;\n }\n if (isCommandWithName(parent, 'pbcopy', 'wl-copy', 'xsel', 'xclip', 'clip.exe')) {\n return true;\n }\n if (isCommandWithName(parent, 'pbpaste', 'wl-paste', 'xsel', 'xclip', 'clip.exe')) {\n return true;\n }\n return false;\n}\n\nexport function getFishBuiltinEquivalentCommandName(node: SyntaxNode): string | null {\n if (!isPosixCommandInsteadOfFishCommand(node)) return null;\n if (!isCommandName(node)) {\n return null;\n }\n const parent = findParentCommand(node);\n if (!parent) return null;\n if (isCommandWithName(parent, 'dirname', 'basename')) {\n return ['path', node.text].join(' ');\n }\n if (isCommandWithName(parent, 'realpath')) {\n return 'path resolve';\n }\n if (isCommandWithName(parent, 'cut')) {\n return 'string split';\n }\n if (isCommandWithName(parent, 'wc')) {\n return 'count';\n }\n if (isCommandWithName(parent, 'pbcopy', 'wl-copy', /*'xsel', 'xclip',*/ 'clip.exe')) {\n return 'fish_clipboard_copy';\n }\n if (isCommandWithName(parent, 'pbpaste', 'wl-paste' /*'xsel', 'xclip', 'powershell.exe'*/)) {\n return 'fish_clipboard_paste';\n }\n if (isCommandWithName(parent, 'xsel', 'xclip')) {\n return 'fish_clipboard_copy | fish_clipboard_paste';\n }\n return null;\n}\n\n// Returns all the autoloaded functions that do not have a `-d`/`--description` option set\nexport function getAutoloadedFunctionsWithoutDescription(doc: LspDocument, handler: DiagnosticCommentsHandler, allFunctions: FishSymbol[]): FishSymbol[] {\n if (!doc.isAutoloaded()) return [];\n return allFunctions.filter((symbol) =>\n symbol.isGlobal()\n && symbol.fishKind !== 'ALIAS'\n && !symbol.node.childrenForFieldName('option').some(child => isMatchingOption(child, Option.create('-d', '--description')))\n && handler.isCodeEnabledAtNode(ErrorCodes.requireAutloadedFunctionHasDescription, symbol.node),\n );\n}\n\n// callback function to check if a function is autoloaded and has an event hook\nexport function isFunctionWithEventHookCallback(doc: LspDocument, handler: DiagnosticCommentsHandler, allFunctions: FishSymbol[]) {\n const docType = doc.getAutoloadType();\n return (node: SyntaxNode): boolean => {\n if (docType !== 'functions') return false;\n if (!isFunctionDefinitionName(node)) return false;\n if (docType === 'functions' && handler.isCodeEnabledAtNode(ErrorCodes.autoloadedFunctionWithEventHookUnused, node)) {\n const funcSymbol = allFunctions.find(symbol => symbol.name === node.text);\n if (funcSymbol && funcSymbol.hasEventHook()) {\n const refs = getReferences(doc, funcSymbol.toPosition()).filter(ref =>\n !funcSymbol.equalsLocation(ref) &&\n !ref.uri.includes('completions/') &&\n ref.uri !== doc.uri,\n );\n if (refs.length === 0) return true;\n }\n }\n return false;\n };\n}\n\nexport function isFishLspDeprecatedVariableName(node: SyntaxNode): boolean {\n if (isVariableDefinitionName(node)) {\n return Config.isDeprecatedKey(node.text);\n }\n if (node.type === 'variable_name') {\n return Config.isDeprecatedKey(node.text);\n }\n return false;\n}\nexport function getDeprecatedFishLspMessage(node: SyntaxNode): string {\n for (const [key, value] of Object.entries(Config.deprecatedKeys)) {\n if (node.text === key) {\n return `REPLACE \\`${key}\\` with \\`${value}\\``;\n }\n }\n return '';\n}\n\n/**\n * Check if a command name is known (builtin, function, or in completion cache)\n * @param commandName - The command name to check\n * @param doc - The current document for context\n * @returns true if the command is known, false otherwise\n */\nexport function isKnownCommand(commandName: string, doc: LspDocument): boolean {\n // Check if it's a builtin command\n if (isBuiltin(commandName)) {\n return true;\n }\n\n // Check if it's a function defined in the workspace\n const globalFunctions = analyzer.globalSymbols.find(commandName);\n if (globalFunctions.length > 0) {\n return true;\n }\n\n // Check if it's a local function in the current document\n const localSymbols = analyzer.getFlatDocumentSymbols(doc.uri);\n if (localSymbols.some(s => s.isFunction() && s.name === commandName)) {\n return true;\n }\n\n // Check all accessible symbols at document level (includes sourced symbols)\n const allAccessibleSymbols = analyzer.allSymbolsAccessibleAtPosition(doc, { line: 0, character: 0 });\n if (allAccessibleSymbols.some(s => s.isFunction() && s.name === commandName)) {\n return true;\n }\n\n // Check the completion cache (includes all commands available at startup)\n if (server) {\n const completions = server.completions;\n const commandCompletions = completions.allOfKinds(\n FishCompletionItemKind.COMMAND,\n FishCompletionItemKind.FUNCTION,\n FishCompletionItemKind.BUILTIN,\n FishCompletionItemKind.ALIAS,\n // FishCompletionItemKind.ABBR,\n );\n if (commandCompletions.some(c => c.label === commandName)) {\n return true;\n }\n }\n\n return false;\n}\n"
},
{
"path": "src/diagnostics/types.ts",
"content": "import { SyntaxNode } from 'web-tree-sitter';\nimport { Diagnostic } from 'vscode-languageserver-protocol';\nimport { ErrorCodes } from './error-codes';\nimport { FishSymbol } from '../parsing/symbol';\n\n// Utilities related to building a documents Diagnostics.\n\n/**\n * Allow the node to be reachable from any Diagnostic\n */\nexport interface FishDiagnostic extends Diagnostic {\n message: string;\n range: any;\n data: {\n node: SyntaxNode;\n fromSymbol: boolean;\n };\n}\n\nexport namespace FishDiagnostic {\n export function create(\n code: ErrorCodes.CodeTypes,\n node: SyntaxNode,\n message: string = '',\n ): FishDiagnostic {\n const errorMessage = message && message.length > 0\n ? ErrorCodes.codes[code].message + ' | ' + message\n : ErrorCodes.codes[code].message;\n return {\n ...ErrorCodes.codes[code],\n range: {\n start: { line: node.startPosition.row, character: node.startPosition.column },\n end: { line: node.endPosition.row, character: node.endPosition.column },\n },\n message: errorMessage,\n data: {\n node,\n fromSymbol: false,\n },\n };\n }\n\n export function fromDiagnostic(diagnostic: Diagnostic): FishDiagnostic {\n return {\n ...diagnostic,\n data: {\n node: undefined as any,\n fromSymbol: false,\n },\n };\n }\n\n export function fromSymbol(code: ErrorCodes.CodeTypes, symbol: FishSymbol): FishDiagnostic {\n const diagnostic = create(code, symbol.focusedNode);\n if (code === ErrorCodes.unusedLocalDefinition) {\n const localSymbolType = symbol.isVariable() ? 'variable' : 'function';\n diagnostic.message += ` ${localSymbolType} '${symbol.name}' is defined but never used.`;\n }\n diagnostic.range = symbol.selectionRange;\n diagnostic.data.fromSymbol = true;\n return diagnostic;\n }\n}\n"
},
{
"path": "src/diagnostics/validate.ts",
"content": "import { Diagnostic, DiagnosticRelatedInformation, Range } from 'vscode-languageserver';\nimport { SyntaxNode } from 'web-tree-sitter';\nimport { LspDocument } from '../document';\nimport { getRange, namedNodesGen } from '../utils/tree-sitter';\nimport { isMatchingOption, Option } from '../parsing/options';\nimport { findErrorCause, isExtraEnd, isZeroIndex, isSingleQuoteVariableExpansion, isUniversalDefinition, isSourceFilename, isTestCommandVariableExpansionWithoutString, isConditionalWithoutQuietCommand, isMatchingCompleteOptionIsCommand, LocalFunctionCallType, isArgparseWithoutEndStdin, isFishLspDeprecatedVariableName, getDeprecatedFishLspMessage, isDotSourceCommand, isMatchingAbbrFunction, isFunctionWithEventHookCallback, isVariableDefinitionWithExpansionCharacter, isPosixCommandInsteadOfFishCommand, getFishBuiltinEquivalentCommandName, getAutoloadedFunctionsWithoutDescription, isWrapperFunction /*isKnownCommand*/ } from './node-types';\nimport { ErrorCodes } from './error-codes';\nimport { config } from '../config';\nimport { DiagnosticCommentsHandler } from './comments-handler';\nimport { logger } from '../logger';\nimport { isAutoloadedUriLoadsFunctionName, uriToReadablePath } from '../utils/translation';\nimport { FishString } from '../parsing/string';\nimport { findParent, findParentCommand, isCommandName, isCommandWithName, isComment, isCompleteCommandName, isFunctionDefinitionName, isOption, isScope, isString, isTopLevelFunctionDefinition } from '../utils/node-types';\nimport { isBuiltin, isReservedKeyword } from '../utils/builtins';\nimport { getNoExecuteDiagnostics } from './no-execute-diagnostic';\nimport { checkForInvalidDiagnosticCodes } from './invalid-error-code';\nimport { analyzer } from '../analyze';\nimport { FishSymbol } from '../parsing/symbol';\nimport { findUnreachableCode } from '../parsing/unreachable';\nimport { allUnusedLocalReferences } from '../references';\nimport { FishDiagnostic } from './types';\nimport { server } from '../server';\nimport { FishCompletionItemKind } from '../utils/completion/types';\n\n// Number of nodes to process before yielding to event loop\nconst CHUNK_SIZE = 100;\n\n/**\n * Async version of getDiagnostics that yields to the event loop periodically\n * to avoid blocking the main thread during diagnostic calculation.\n *\n * This function has identical behavior to getDiagnostics(), but processes\n * nodes in chunks and yields between chunks using setImmediate().\n *\n * @param root - The root syntax node of the document\n * @param doc - The LspDocument being analyzed\n * @param signal - Optional AbortSignal to cancel the computation\n * @param maxDiagnostics - Optional limit on number of diagnostics to return (0 = unlimited)\n * @returns Promise resolving to array of diagnostics\n */\nexport async function getDiagnosticsAsync(\n root: SyntaxNode,\n doc: LspDocument,\n signal?: AbortSignal,\n maxDiagnostics: number = config.fish_lsp_max_diagnostics,\n): Promise {\n const diagnostics: Diagnostic[] = [];\n\n // Helper to check if we've hit the diagnostic limit\n const hasReachedLimit = () => maxDiagnostics > 0 && diagnostics.length >= maxDiagnostics;\n\n // Helper to add diagnostics and check if limit was reached\n const addDiagnostics = (...diags: Diagnostic[]): boolean => {\n diagnostics.push(...diags);\n return hasReachedLimit();\n };\n\n const handler = new DiagnosticCommentsHandler();\n const isAutoloadedFunctionName = isAutoloadedUriLoadsFunctionName(doc);\n\n const docType = doc.getAutoloadType();\n\n // arrays to keep track of different groups of functions\n const allFunctions: FishSymbol[] = analyzer.getFlatDocumentSymbols(doc.uri).filter(s => s.isFunction());\n const autoloadedFunctions: SyntaxNode[] = [];\n const topLevelFunctions: SyntaxNode[] = [];\n const functionsWithReservedKeyword: SyntaxNode[] = [];\n\n const localFunctions: SyntaxNode[] = [];\n const localFunctionCalls: LocalFunctionCallType[] = [];\n const commandNames: SyntaxNode[] = [];\n const completeCommandNames: SyntaxNode[] = [];\n\n // handles and returns true/false if the node is a variable definition with an expansion character\n const definedVariables: { [name: string]: SyntaxNode[]; } = {};\n\n // callback to check if the function has an `--event` handler && the handler is enabled at the node\n const isFunctionWithEventHook = isFunctionWithEventHookCallback(doc, handler, allFunctions);\n\n // Process nodes in chunks to avoid blocking the main thread\n // Using generator for better memory efficiency\n let i = 0;\n for (const node of namedNodesGen(root)) {\n // Check if computation was cancelled\n if (signal?.aborted) {\n logger.warning('Diagnostic computation cancelled');\n return diagnostics;\n }\n\n // Early exit if we've hit the diagnostic limit\n if (hasReachedLimit()) {\n return diagnostics;\n }\n\n handler.handleNode(node);\n\n // Check for invalid diagnostic codes first\n const invalidDiagnosticCodes = checkForInvalidDiagnosticCodes(node);\n if (invalidDiagnosticCodes.length > 0) {\n // notice, this is the only case where we don't check if the user has disabled the error code\n // because `# @fish-lsp-disable` will always be recognized as a disabled error code\n if (addDiagnostics(...invalidDiagnosticCodes)) return diagnostics;\n }\n\n if (isComment(node)) {\n continue;\n }\n\n if (node.type === 'variable_name' || node.text.startsWith('$') || isString(node)) {\n const parent = findParentCommand(node);\n if (parent && isCommandWithName(parent, 'set', 'test')) {\n const opt = isCommandWithName(parent, 'test') ? Option.short('-n') : Option.create('-q', '--query');\n let text = FishString.fromNode(node);\n if (text.startsWith('$')) text = text.slice(1);\n if (text && text.length !== 0) {\n const scope = findParent(node, n => isScope(n));\n if (scope && parent.children.some(c => isMatchingOption(c, opt))) {\n definedVariables[text] = definedVariables[text] || [];\n definedVariables[text]?.push(scope);\n }\n }\n }\n }\n\n if (node.isError) {\n const found: SyntaxNode | null = findErrorCause(node.children);\n if (found && handler.isCodeEnabled(ErrorCodes.missingEnd)) {\n if (addDiagnostics(FishDiagnostic.create(ErrorCodes.missingEnd, node))) return diagnostics;\n }\n }\n\n if (isExtraEnd(node) && handler.isCodeEnabled(ErrorCodes.extraEnd)) {\n if (addDiagnostics(FishDiagnostic.create(ErrorCodes.extraEnd, node))) return diagnostics;\n }\n\n if (isZeroIndex(node) && handler.isCodeEnabled(ErrorCodes.missingEnd)) {\n if (addDiagnostics(FishDiagnostic.create(ErrorCodes.zeroIndexedArray, node))) return diagnostics;\n }\n\n if (isSingleQuoteVariableExpansion(node) && handler.isCodeEnabled(ErrorCodes.singleQuoteVariableExpansion)) {\n // don't add this diagnostic if the autoload type is completions\n if (doc.getAutoloadType() !== 'completions') {\n if (addDiagnostics(FishDiagnostic.create(ErrorCodes.singleQuoteVariableExpansion, node))) return diagnostics;\n }\n }\n\n if (isWrapperFunction(node, handler)) {\n if (addDiagnostics(FishDiagnostic.create(ErrorCodes.usedWrapperFunction, node))) return diagnostics;\n }\n\n if (isUniversalDefinition(node) && docType !== 'conf.d' && handler.isCodeEnabled(ErrorCodes.usedUnviersalDefinition)) {\n if (addDiagnostics(FishDiagnostic.create(ErrorCodes.usedUnviersalDefinition, node))) return diagnostics;\n }\n\n if (isPosixCommandInsteadOfFishCommand(node) && handler.isCodeEnabled(ErrorCodes.usedExternalShellCommandWhenBuiltinExists)) {\n const diagnostic = FishDiagnostic.create(\n ErrorCodes.usedExternalShellCommandWhenBuiltinExists,\n node,\n `Use the Fish builtin command '${getFishBuiltinEquivalentCommandName(node)!}' instead of the external shell command.`,\n );\n if (addDiagnostics(diagnostic)) return diagnostics;\n }\n if (isSourceFilename(node) && handler.isCodeEnabled(ErrorCodes.sourceFileDoesNotExist)) {\n if (addDiagnostics(FishDiagnostic.create(ErrorCodes.sourceFileDoesNotExist, node))) return diagnostics;\n }\n\n if (isDotSourceCommand(node) && handler.isCodeEnabled(ErrorCodes.dotSourceCommand)) {\n if (addDiagnostics(FishDiagnostic.create(ErrorCodes.dotSourceCommand, node))) return diagnostics;\n }\n\n if (isTestCommandVariableExpansionWithoutString(node) && handler.isCodeEnabled(ErrorCodes.testCommandMissingStringCharacters)) {\n if (addDiagnostics(FishDiagnostic.create(ErrorCodes.testCommandMissingStringCharacters, node))) return diagnostics;\n }\n\n if (isConditionalWithoutQuietCommand(node) && handler.isCodeEnabled(ErrorCodes.missingQuietOption)) {\n logger.log('isConditionalWithoutQuietCommand', { type: node.type, text: node.text });\n const command = node.firstNamedChild || node;\n let subCommand = command;\n if (command.text.includes('string')) {\n subCommand = command.nextSibling || node.nextSibling!;\n }\n const range: Range = {\n start: { line: command.startPosition.row, character: command.startPosition.column },\n end: { line: subCommand.endPosition.row, character: subCommand.endPosition.column },\n };\n\n if (addDiagnostics({\n ...FishDiagnostic.create(ErrorCodes.missingQuietOption, node),\n range,\n })) return diagnostics;\n }\n\n if (isArgparseWithoutEndStdin(node) && handler.isCodeEnabled(ErrorCodes.argparseMissingEndStdin)) {\n if (addDiagnostics(FishDiagnostic.create(ErrorCodes.argparseMissingEndStdin, node))) return diagnostics;\n }\n\n // store the defined variable expansions and then use them in the next check\n if (isVariableDefinitionWithExpansionCharacter(node, definedVariables) && handler.isCodeEnabled(ErrorCodes.dereferencedDefinition)) {\n if (addDiagnostics(FishDiagnostic.create(ErrorCodes.dereferencedDefinition, node))) return diagnostics;\n }\n\n if (isFishLspDeprecatedVariableName(node) && handler.isCodeEnabled(ErrorCodes.fishLspDeprecatedEnvName)) {\n logger.log('isFishLspDeprecatedVariableName', doc.getText(getRange(node)));\n if (addDiagnostics(FishDiagnostic.create(ErrorCodes.fishLspDeprecatedEnvName, node, getDeprecatedFishLspMessage(node)))) return diagnostics;\n }\n\n /** store any functions we see, to reuse later */\n if (isFunctionDefinitionName(node)) {\n if (isAutoloadedFunctionName(node)) autoloadedFunctions.push(node);\n if (isTopLevelFunctionDefinition(node)) topLevelFunctions.push(node);\n if (isReservedKeyword(node.text)) functionsWithReservedKeyword.push(node);\n if (!isAutoloadedFunctionName(node)) localFunctions.push(node);\n if (isFunctionWithEventHook(node)) {\n // TODO: add support for `emit` to reference the event hook\n if (addDiagnostics(\n FishDiagnostic.create(\n ErrorCodes.autoloadedFunctionWithEventHookUnused,\n node,\n `Function '${node.text}' has an event hook but is not called anywhere in the workspace.`,\n ),\n )) return diagnostics;\n }\n }\n\n // skip options like: '-f'\n if (isOption(node)) {\n // Yield to event loop every CHUNK_SIZE iterations\n if (++i % CHUNK_SIZE === 0) {\n await new Promise(resolve => setImmediate(resolve));\n }\n continue;\n }\n\n /** keep this section at end of loop iteration, because it uses continue */\n if (isCommandName(node)) commandNames.push(node);\n\n // get the parent and previous sibling, for the next checks\n const { parent, previousSibling } = node;\n if (!parent || !previousSibling) {\n // Yield to event loop every CHUNK_SIZE iterations\n if (++i % CHUNK_SIZE === 0) {\n await new Promise(resolve => setImmediate(resolve));\n }\n continue;\n }\n\n // skip if this is an abbr function, since we don't want to complete abbr functions\n if (isCommandWithName(parent, 'abbr') && isMatchingAbbrFunction(previousSibling)) {\n localFunctionCalls.push({ node, text: node.text });\n // Yield to event loop every CHUNK_SIZE iterations\n if (++i % CHUNK_SIZE === 0) {\n await new Promise(resolve => setImmediate(resolve));\n }\n continue;\n }\n\n // if the current node is a bind subcommand `bind ctrl-k ` where `` gets added to the localFunctionCalls\n if (isCommandWithName(parent, 'bind')) {\n const subcommands = parent.children.slice(2).filter(c => !isOption(c));\n subcommands.forEach(subcommand => {\n if (isString(subcommand)) {\n // like this example: `(cmd; and cmd2)`\n // we remove the characters: `( ; and )`\n localFunctionCalls.push({\n node,\n text: subcommand.text.slice(1, -1)\n .replace(/[\\(\\)]/g, '') // Remove parentheses\n .replace(/[^\\u0020-\\u007F]/g, ''), // Keep only ASCII printable chars\n });\n return;\n }\n localFunctionCalls.push({ node, text: subcommand.text });\n });\n // Yield to event loop every CHUNK_SIZE iterations\n if (++i % CHUNK_SIZE === 0) {\n await new Promise(resolve => setImmediate(resolve));\n }\n continue;\n }\n\n // for autoloaded files that could have completions, we only want to check for `complete` commands\n if (doc.isAutoloadedWithPotentialCompletions()) {\n if (isCompleteCommandName(node)) completeCommandNames.push(node);\n // skip if no parent command (note we already added commands above)\n if (!isCommandWithName(parent, 'complete')) {\n // Yield to event loop every CHUNK_SIZE iterations\n if (++i % CHUNK_SIZE === 0) {\n await new Promise(resolve => setImmediate(resolve));\n }\n continue;\n }\n // skip if no previous sibling (since we're looking for `complete -n/-a/-c `)\n if (isMatchingCompleteOptionIsCommand(previousSibling)) {\n // if we find a string, remove unnecessary tokens from arguments\n if (isString(node)) {\n // like this example: `(cmd; and cmd2)`\n // we remove the characters: `( ; and )`\n localFunctionCalls.push({\n node,\n text: node.text.slice(1, -1)\n .replace(/[\\(\\)]/g, '') // Remove parentheses\n .replace(/[^\\u0020-\\u007F]/g, ''), // Keep only ASCII printable chars\n });\n // Yield to event loop every CHUNK_SIZE iterations\n if (++i % CHUNK_SIZE === 0) {\n await new Promise(resolve => setImmediate(resolve));\n }\n continue;\n }\n // otherwise, just add the node as is (should just be an unquoted command)\n localFunctionCalls.push({ node, text: node.text });\n }\n }\n\n // Yield to event loop every CHUNK_SIZE iterations\n if (++i % CHUNK_SIZE === 0) {\n await new Promise(resolve => setImmediate(resolve));\n }\n }\n\n // Check if computation was cancelled before post-processing\n if (signal?.aborted) {\n logger.warning('Diagnostic computation cancelled');\n return diagnostics;\n }\n\n // Skip post-processing if we've already hit the diagnostic limit\n if (hasReachedLimit()) {\n return diagnostics;\n }\n\n // allow nodes outside of the loop, to retrieve the old state\n handler.finalizeStateMap(root.text.split('\\n').length + 1);\n\n const isMissingAutoloadedFunction = docType === 'functions'\n ? autoloadedFunctions.length === 0\n : false;\n\n const isMissingAutoloadedFunctionButContainsOtherFunctions =\n isMissingAutoloadedFunction && topLevelFunctions.length > 0;\n\n // no function definition for autoloaded function file\n if (isMissingAutoloadedFunction && topLevelFunctions.length === 0 && handler.isCodeEnabledAtNode(ErrorCodes.autoloadedFunctionMissingDefinition, root)) {\n if (addDiagnostics(FishDiagnostic.create(ErrorCodes.autoloadedFunctionMissingDefinition, root))) return diagnostics;\n }\n // has functions/file.fish has top level functions, but none match the filename\n if (isMissingAutoloadedFunctionButContainsOtherFunctions) {\n topLevelFunctions.forEach(node => {\n if (handler.isCodeEnabledAtNode(ErrorCodes.autoloadedFunctionFilenameMismatch, node)) {\n if (addDiagnostics(FishDiagnostic.create(ErrorCodes.autoloadedFunctionFilenameMismatch, node))) return diagnostics;\n }\n });\n }\n // has functions with invalid names -- (reserved keywords)\n functionsWithReservedKeyword.forEach(node => {\n if (handler.isCodeEnabledAtNode(ErrorCodes.functionNameUsingReservedKeyword, node)) {\n if (addDiagnostics(FishDiagnostic.create(ErrorCodes.functionNameUsingReservedKeyword, node))) return diagnostics;\n }\n });\n\n // get all function definitions in the document\n const duplicateFunctions: { [name: string]: FishSymbol[]; } = {};\n allFunctions.forEach(node => {\n const currentDupes = duplicateFunctions[node.name] ?? [];\n currentDupes.push(node);\n duplicateFunctions[node.name] = currentDupes;\n });\n\n // Add diagnostics for duplicate function definitions in the same scope\n Object.entries(duplicateFunctions).forEach(([_, functionSymbols]) => {\n // skip single function definitions\n if (functionSymbols.length <= 1) return;\n functionSymbols.forEach(n => {\n if (handler.isCodeEnabledAtNode(ErrorCodes.duplicateFunctionDefinitionInSameScope, n.focusedNode)) {\n // dupes are the array of all function symbols that have the same name and scope as the current symbol `n`\n const dupes = functionSymbols.filter(s => s.scopeNode.equals(n.scopeNode) && !s.equals(n)) ?? [] as FishSymbol[];\n // skip if the function is defined in a different scope\n if (dupes.length < 1) return;\n // create a diagnostic for the duplicate function definition\n const diagnostic = FishDiagnostic.create(ErrorCodes.duplicateFunctionDefinitionInSameScope, n.focusedNode);\n diagnostic.range = n.selectionRange;\n // plus one because the dupes array does not include the current symbol `n`\n diagnostic.message += ` '${n.name}' is defined ${dupes.length + 1} time(s) in ${n.scopeTag.toUpperCase()} scope.`;\n diagnostic.message += `\\n\\nFILE: ${uriToReadablePath(n.uri)}`;\n // diagnostic.data.symbol = n;\n diagnostic.relatedInformation = dupes.filter(s => !s.equals(n)).map(s => DiagnosticRelatedInformation.create(\n s.toLocation(),\n `${s.scopeTag.toUpperCase()} duplicate '${s.name}' defined on line ${s.focusedNode.startPosition.row}`,\n ));\n if (addDiagnostics(diagnostic)) return diagnostics;\n }\n });\n });\n\n // `4008` -> auto-loaded functions without description\n getAutoloadedFunctionsWithoutDescription(doc, handler, allFunctions).forEach((symbol) => {\n if (addDiagnostics(FishDiagnostic.fromSymbol(ErrorCodes.requireAutloadedFunctionHasDescription, symbol))) return diagnostics;\n });\n\n localFunctions.forEach(node => {\n const matches = commandNames.filter(call => call.text === node.text);\n if (matches.length === 0) return;\n if (!localFunctionCalls.some(call => call.text === node.text)) {\n localFunctionCalls.push({ node, text: node.text });\n }\n });\n\n const docNameMatchesCompleteCommandNames = completeCommandNames.some(node =>\n FishString.fromNode(node) === doc.getAutoLoadName());\n // if no `complete -c func_name` matches the autoload name\n if (completeCommandNames.length > 0 && !docNameMatchesCompleteCommandNames && doc.isAutoloadedCompletion()) {\n const completeNames: Set = new Set();\n for (const completeCommandName of completeCommandNames) {\n if (!completeNames.has(FishString.fromNode(completeCommandName)) && handler.isCodeEnabledAtNode(ErrorCodes.autoloadedCompletionMissingCommandName, completeCommandName)) {\n if (addDiagnostics(FishDiagnostic.create(ErrorCodes.autoloadedCompletionMissingCommandName, completeCommandName, completeCommandName.text))) return diagnostics;\n completeNames.add(FishString.fromNode(completeCommandName));\n }\n }\n }\n\n // 4004 -> unused local function/variable definitions\n if (handler.isRootEnabled(ErrorCodes.unusedLocalDefinition)) {\n const unusedLocalDefinitions = allUnusedLocalReferences(doc);\n for (const unusedLocalDefinition of unusedLocalDefinitions) {\n // skip definitions that do not need local references\n if (!unusedLocalDefinition.needsLocalReferences()) {\n logger.debug('Skipping unused local definition', {\n name: unusedLocalDefinition.name,\n uri: unusedLocalDefinition.uri,\n type: unusedLocalDefinition.kind,\n });\n continue;\n }\n if (handler.isCodeEnabledAtNode(ErrorCodes.unusedLocalDefinition, unusedLocalDefinition.focusedNode)) {\n if (addDiagnostics(\n FishDiagnostic.fromSymbol(ErrorCodes.unusedLocalDefinition, unusedLocalDefinition),\n )) return diagnostics;\n }\n }\n }\n\n // 5555 -> code is not reachable\n if (handler.isRootEnabled(ErrorCodes.unreachableCode)) {\n const unreachableNodes = findUnreachableCode(root);\n for (const unreachableNode of unreachableNodes) {\n if (handler.isCodeEnabledAtNode(ErrorCodes.unreachableCode, unreachableNode)) {\n if (addDiagnostics(FishDiagnostic.create(ErrorCodes.unreachableCode, unreachableNode))) return diagnostics;\n }\n }\n }\n\n // 7001 -> unknown command\n if (handler.isRootEnabled(ErrorCodes.unknownCommand)) {\n // Cache expensive lookups that are reused for every command\n const knownCommandsCache = new Set();\n const unknownCommandsCache = new Set();\n\n // Pre-compute expensive lookups once\n const localSymbols = analyzer.getFlatDocumentSymbols(doc.uri);\n const localFunctionNames = new Set(localSymbols.filter(s => s.isFunction()).map(s => s.name));\n const allAccessibleSymbols = analyzer.allReachableSymbols(doc.uri);\n\n // Pre-load completion cache if available\n let commandCompletions: Set | null = null;\n if (server) {\n const completions = server.completions;\n const commandCompletionList = completions.allOfKinds(\n FishCompletionItemKind.ALIAS,\n FishCompletionItemKind.BUILTIN,\n FishCompletionItemKind.FUNCTION,\n FishCompletionItemKind.COMMAND,\n );\n commandCompletions = new Set(commandCompletionList.map(c => c.label));\n }\n\n for (const commandNode of commandNames) {\n const commandName = commandNode.text.trim();\n\n // Skip empty commands or commands that are already errors\n if (!commandName || commandNode.isError) {\n continue;\n }\n\n if (!handler.isCodeEnabledAtNode(ErrorCodes.unknownCommand, commandNode)) {\n continue;\n }\n\n // Skip commands that are actually relative paths (start with '.')\n if (commandName.startsWith('.') || commandName.includes('/')) {\n continue;\n }\n\n // Check cache first\n if (knownCommandsCache.has(commandName)) {\n continue;\n }\n if (unknownCommandsCache.has(commandName)) {\n if (handler.isCodeEnabledAtNode(ErrorCodes.unknownCommand, commandNode)) {\n if (addDiagnostics(\n FishDiagnostic.create(\n ErrorCodes.unknownCommand,\n commandNode,\n `'${commandName}' is not a known builtin, function, or command`,\n ),\n )) return diagnostics;\n }\n continue;\n }\n\n // Check if command is known (using cached data)\n let isKnown = false;\n\n // Check builtins (fast)\n if (isBuiltin(commandName)) {\n isKnown = true;\n } else if (localFunctionNames.has(commandName)) {\n // Check local functions (cached)\n isKnown = true;\n } else if (allAccessibleSymbols.some(s => s.name === commandName)) {\n // Check accessible functions (cached)\n isKnown = true;\n } else if (analyzer.globalSymbols.find(commandName).length > 0) {\n // Check global symbols\n isKnown = true;\n } else if (commandCompletions && commandCompletions.has(commandName)) {\n // Check completion cache (cached)\n isKnown = true;\n }\n\n // Update cache\n if (isKnown) {\n knownCommandsCache.add(commandName);\n } else {\n unknownCommandsCache.add(commandName);\n if (handler.isCodeEnabledAtNode(ErrorCodes.unknownCommand, commandNode)) {\n if (addDiagnostics(\n FishDiagnostic.create(\n ErrorCodes.unknownCommand,\n commandNode,\n `'${commandName}' is not a known builtin, function, or command`,\n ),\n )) return diagnostics;\n }\n }\n }\n }\n\n // add 9999 diagnostics from `fish --no-execute` if the user enabled it\n if (config.fish_lsp_enable_experimental_diagnostics) {\n const noExecuteDiagnostics = getNoExecuteDiagnostics(doc);\n for (const diagnostic of noExecuteDiagnostics) {\n if (handler.isCodeEnabledAtNode(ErrorCodes.syntaxError, diagnostic.data.node)) {\n if (addDiagnostics(diagnostic)) return diagnostics;\n }\n }\n }\n\n return diagnostics;\n}\n"
},
{
"path": "src/document-highlight.ts",
"content": "import { Analyzer } from './analyze';\nimport { getRange } from './utils/tree-sitter';\nimport { DocumentHighlight, DocumentHighlightKind, DocumentHighlightParams, Location } from 'vscode-languageserver';\nimport { isCommandName } from './utils/node-types';\nimport { LspDocument } from './document';\nimport { getReferences } from './references';\nimport { isBuiltin } from './utils/builtins';\n\n/**\n * TODO:\n * ADD DocumentHighlightKind.Read | DocumentHighlightKind.Write support\n */\nexport function getDocumentHighlights(analyzer: Analyzer) {\n function convertSymbolLocationsToHighlights(doc: LspDocument, locations: Location[]): DocumentHighlight[] {\n return locations\n .filter(loc => loc.uri === doc.uri)\n .map(loc => {\n return {\n range: loc.range,\n kind: DocumentHighlightKind.Text,\n };\n });\n }\n\n return function(params: DocumentHighlightParams): DocumentHighlight[] {\n const { uri } = params.textDocument;\n const { line, character } = params.position;\n const doc = analyzer.getDocument(uri);\n if (!doc) return [];\n\n const word = analyzer.wordAtPoint(uri, line, character);\n if (!word || word.trim() === '') return [];\n\n const nodes = analyzer.getNodes(uri);\n\n // check if the word is a builtin function\n if (isBuiltin(word)) {\n return nodes\n .filter(n => isBuiltin(n.text) && n.text === word)\n .map(n => {\n return {\n range: getRange(n),\n kind: DocumentHighlightKind.Text,\n };\n });\n }\n\n const symbol = analyzer.getDefinition(doc, params.position);\n const node = analyzer.nodeAtPoint(uri, line, character);\n if (!node || !node.isNamed) return [];\n\n // check if a node is a command name\n if (!symbol && isCommandName(node)) {\n const matchingCommandNodes =\n nodes.filter(n => isCommandName(n) && n.text === node.text);\n\n return matchingCommandNodes.map(n => {\n return {\n range: getRange(n),\n kind: DocumentHighlightKind.Text,\n };\n });\n }\n\n // use local symbol reference locations\n if (symbol) {\n const refLocations = getReferences(doc, symbol.selectionRange.start, { localOnly: true });\n if (!refLocations) return [];\n return convertSymbolLocationsToHighlights(doc, refLocations);\n }\n\n return [];\n };\n}\n"
},
{
"path": "src/document.ts",
"content": "import * as path from 'path';\nimport { homedir } from 'os';\nimport { promises } from 'fs';\nimport { TextDocument } from 'vscode-languageserver-textdocument';\nimport { Position, Range, TextDocumentItem, TextDocumentContentChangeEvent, VersionedTextDocumentIdentifier, TextDocumentIdentifier, DocumentUri } from 'vscode-languageserver';\nimport { TextDocuments } from 'vscode-languageserver/node';\nimport { workspaceManager } from './utils/workspace-manager';\nimport { AutoloadType, isPath, isTextDocument, isTextDocumentItem, isUri, PathLike, pathToUri, uriToPath } from './utils/translation';\nimport { Workspace } from './utils/workspace';\nimport { SyncFileHelper } from './utils/file-operations';\nimport { logger } from './logger';\nimport * as Locations from './utils/locations';\nimport { FishSymbol } from './parsing/symbol';\nimport { logTreeSitterDocumentDebug, returnParseTreeString } from './utils/cli-dump-tree';\n\nexport class LspDocument implements TextDocument {\n protected document: TextDocument;\n public lastChangedLineSpan?: LineSpan;\n\n constructor(doc: TextDocumentItem) {\n const { uri, languageId, version, text } = doc;\n this.document = TextDocument.create(uri, languageId, version, text);\n this.lastChangedLineSpan = computeChangedLineSpan([{ text }]);\n }\n static createTextDocumentItem(uri: string, text: string): LspDocument {\n return new LspDocument({\n uri,\n languageId: 'fish',\n version: 1,\n text,\n });\n }\n\n static fromTextDocument(doc: TextDocument): LspDocument {\n const item = TextDocumentItem.create(doc.uri, doc.languageId, doc.version, doc.getText());\n return new LspDocument(item);\n }\n\n static createFromUri(uri: DocumentUri): LspDocument {\n const content = SyncFileHelper.read(uriToPath(uri));\n return LspDocument.createTextDocumentItem(uri, content);\n }\n\n static createFromPath(path: PathLike): LspDocument {\n const content = SyncFileHelper.read(path);\n return LspDocument.createTextDocumentItem(pathToUri(path), content);\n }\n\n static testUri(uri: DocumentUri): string {\n const removeString = 'tests/workspaces';\n if (uri.includes(removeString)) {\n return 'file:///…/' + uri.slice(uri.indexOf(removeString) + removeString.length + 1);\n }\n return uri;\n }\n\n static testUtil(uri: DocumentUri) {\n const shortUri = LspDocument.testUri(uri);\n const fullPath = uriToPath(uri);\n\n const parentDir = path.dirname(fullPath);\n const relativePath = shortUri.slice(shortUri.indexOf(parentDir) + parentDir.length + 1);\n\n return {\n uri,\n shortUri,\n fullPath,\n relativePath,\n parentDir,\n };\n }\n\n static create(\n uri: string,\n languageId: string,\n version: number,\n text: string,\n ): LspDocument {\n const inner = TextDocument.create(uri, languageId, version, text);\n return new LspDocument({ uri: inner.uri, languageId: inner.languageId, version: inner.version, text: inner.getText() });\n }\n\n static update(\n doc: LspDocument,\n changes: TextDocumentContentChangeEvent[],\n version: number,\n ): LspDocument {\n doc.document = TextDocument.update(doc.document, changes, version);\n doc.lastChangedLineSpan = computeChangedLineSpan(changes);\n return doc;\n }\n\n /**\n * Creates a new LspDocument from a path, URI, TextDocument, TextDocumentItem, or another LspDocument.\n * @param param The parameter to create the LspDocument from.\n * @returns A new LspDocument instance.\n */\n static createFrom(uri: DocumentUri): LspDocument;\n static createFrom(path: PathLike): LspDocument;\n static createFrom(doc: TextDocument): LspDocument;\n static createFrom(doc: TextDocumentItem): LspDocument;\n static createFrom(doc: LspDocument): LspDocument;\n static createFrom(param: PathLike | DocumentUri | TextDocument | TextDocumentItem | LspDocument): LspDocument;\n static createFrom(param: PathLike | DocumentUri | TextDocument | TextDocumentItem | LspDocument): LspDocument {\n if (typeof param === 'string' && isPath(param)) return LspDocument.createFromPath(param);\n if (typeof param === 'string' && isUri(param)) return LspDocument.createFromUri(param);\n if (LspDocument.is(param)) return LspDocument.fromTextDocument(param.document);\n if (isTextDocumentItem(param)) return LspDocument.createTextDocumentItem(param.uri, param.text);\n if (isTextDocument(param)) return LspDocument.fromTextDocument(param);\n // we should never reach here\n logger.error('Invalid parameter type `LspDocument.create()`: ', param);\n return undefined as never;\n }\n\n static async createFromUriAsync(uri: DocumentUri): Promise {\n const content = await promises.readFile(uriToPath(uri), 'utf8');\n return LspDocument.createTextDocumentItem(uri, content);\n }\n\n asTextDocumentItem(): TextDocumentItem {\n return {\n uri: this.document.uri,\n languageId: this.document.languageId,\n version: this.document.version,\n text: this.document.getText(),\n };\n }\n\n asTextDocumentIdentifier(): TextDocumentIdentifier {\n return {\n uri: this.document.uri,\n };\n }\n\n get uri(): DocumentUri {\n return this.document.uri;\n }\n\n get languageId(): string {\n return this.document.languageId;\n }\n\n get version(): number {\n return this.document.version;\n }\n\n get path(): string {\n return uriToPath(this.document.uri);\n }\n\n /**\n * Fallback span that covers the entire document\n */\n get fullSpan() {\n return {\n start: 0,\n end: this.positionAt(this.getText().length).line,\n };\n }\n\n getText(range?: Range): string {\n return this.document.getText(range);\n }\n\n positionAt(offset: number): Position {\n return this.document.positionAt(offset);\n }\n\n offsetAt(position: Position): number {\n return this.document.offsetAt(position);\n }\n\n get lineCount(): number {\n return this.document.lineCount;\n }\n\n create(uri: string, languageId: string, version: number, text: string): LspDocument {\n return new LspDocument({\n uri,\n languageId: languageId || 'fish',\n version: version || 1,\n text,\n });\n }\n\n /**\n * @see getLineBeforeCursor()\n */\n getLine(line: number | Position | Range | FishSymbol): string {\n if (Locations.Position.is(line)) {\n line = line.line;\n } else if (Locations.Range.is(line)) {\n line = line.start.line;\n } else if (FishSymbol.is(line)) {\n line = line.range.start.line;\n }\n const lines = this.document.getText().split('\\n');\n return lines[line] || '';\n }\n\n getLineBeforeCursor(position: Position): string {\n const lineStart = Position.create(position.line, 0);\n const lineEnd = Position.create(position.line, position.character);\n const lineRange = Range.create(lineStart, lineEnd);\n return this.getText(lineRange);\n }\n\n getLineRange(line: number): Range {\n const lineStart = this.getLineStart(line);\n const lineEnd = this.getLineEnd(line);\n return Range.create(lineStart, lineEnd);\n }\n\n getLineEnd(line: number): Position {\n const nextLineOffset = this.getLineOffset(line + 1);\n return this.positionAt(nextLineOffset - 1);\n }\n\n getLineOffset(line: number): number {\n const lineStart = this.getLineStart(line);\n return this.offsetAt(lineStart);\n }\n\n getLineStart(line: number): Position {\n return Position.create(line, 0);\n }\n\n getIndentAtLine(line: number): string {\n const lineText = this.getLine(line);\n const indent = lineText.match(/^\\s+/);\n return indent ? indent[0] : '';\n }\n\n /**\n * Apply incremental LSP changes to this document.\n *\n * @param changes TextDocumentContentChangeEvent[] from textDocument/didChange\n * @param version Optional LSP version; if omitted, increments current version\n */\n update(changes: TextDocumentContentChangeEvent[], version?: number): void {\n const newVersion = version ?? this.version + 1;\n this.document = TextDocument.update(this.document, changes, newVersion);\n }\n\n asVersionedIdentifier() {\n return VersionedTextDocumentIdentifier.create(this.uri, this.version);\n }\n\n rename(newUri: string): void {\n this.document = TextDocument.create(newUri, this.languageId, this.version, this.getText());\n }\n\n getFilePath(): string {\n return uriToPath(this.uri);\n }\n\n getFilename(): string {\n return this.uri.split('/').pop() as string;\n }\n\n getRelativeFilenameToWorkspace(): string {\n const home = homedir();\n const path = this.uri.replace(home, '~');\n const dirs = path.split('/');\n if (this.isCommandlineBuffer() || this.isFunced()) {\n return this.path.split('/').pop() as string;\n }\n const workspaceRootIndex = dirs.find(dir => dir === 'fish')\n ? dirs.indexOf('fish')\n : dirs.find(dir => ['conf.d', 'functions', 'completions', 'config.fish'].includes(dir))\n // ? dirs.findLastIndex(dir => ['conf.d', 'functions', 'completions', 'config.fish'].includes(dir))\n ? dirs.findIndex(dir => ['conf.d', 'functions', 'completions', 'config.fish'].includes(dir))\n : dirs.length - 1;\n\n return dirs.slice(workspaceRootIndex).join('/');\n }\n\n /**\n * checks if the functions are defined in a functions directory\n */\n isFunction(): boolean {\n const pathArray = this.uri.split('/');\n const fileName = pathArray.pop();\n const parentDir = pathArray.pop();\n /** paths that autoload all top level functions to the shell env */\n if (parentDir === 'conf.d' || fileName === 'config.fish') {\n return true;\n }\n /** path that autoload matching filename functions to the shell env */\n return parentDir === 'functions';\n }\n\n isAutoloadedFunction(): boolean {\n return this.getAutoloadType() === 'functions';\n }\n\n isAutoloadedCompletion(): boolean {\n return this.getAutoloadType() === 'completions';\n }\n\n isAutoloadedConfd(): boolean {\n return this.getAutoloadType() === 'conf.d';\n }\n\n shouldAnalyzeInBackground(): boolean {\n const pathArray = this.uri.split('/');\n const fileName = pathArray.pop();\n const parentDir = pathArray.pop();\n return parentDir && ['functions', 'conf.d', 'completions'].includes(parentDir?.toString()) || fileName === 'config.fish';\n }\n\n public getWorkspace(): Workspace | undefined {\n return workspaceManager.findContainingWorkspace(this.uri) || undefined;\n }\n\n private getFolderType(): AutoloadType | null {\n const docPath = uriToPath(this.uri);\n if (!docPath) return null;\n\n // Treat funced files as if they were in the functions directory\n if (this.isFunced()) return 'functions';\n if (this.isCommandlineBuffer()) return 'conf.d';\n\n const dirName = path.basename(path.dirname(docPath));\n const fileName = path.basename(docPath);\n\n if (dirName === 'functions') return 'functions';\n if (dirName === 'conf.d') return 'conf.d';\n if (dirName === 'completions') return 'completions';\n if (fileName === 'config.fish') return 'config';\n\n return '';\n }\n\n /**\n * checks if the document is in a location where the functions\n * that it defines are autoloaded by fish.\n *\n * Use isAutoloadedUri() if you want to check for completions\n * files as well. This function does not check for completion\n * files.\n */\n isAutoloaded(): boolean {\n const folderType = this.getFolderType();\n if (!folderType) return false;\n if (this.isFunced()) return true;\n return ['functions', 'conf.d', 'config'].includes(folderType);\n }\n\n isFunced(): boolean {\n return LspDocument.isFuncedPath(this.path);\n }\n\n isCommandlineBuffer(): boolean {\n return LspDocument.isCommandlineBufferPath(this.path);\n }\n\n static isFuncedPath(path: string): boolean {\n return path.startsWith('/tmp/fish-funced.');\n }\n\n static isCommandlineBufferPath(path: string): boolean {\n return path.startsWith('/tmp/fish.') && path.endsWith('command-line.fish');\n }\n\n /**\n * checks if the document is in a location:\n * - `fish/{conf.d,functions,completions}/file.fish`\n * - `fish/config.fish`\n *\n * Key difference from isAutoLoaded is that this function checks for\n * completions files as well. isAutoloaded() does not check for\n * completion files.\n */\n isAutoloadedUri(): boolean {\n const folderType = this.getFolderType();\n if (!folderType) return false;\n return ['functions', 'conf.d', 'config', 'completions'].includes(folderType);\n }\n\n /**\n * checks if the document is in a location where it is autoloaded\n * @returns {boolean} - true if the document is in a location that could contain `complete` definitions\n */\n isAutoloadedWithPotentialCompletions(): boolean {\n const folderType = this.getFolderType();\n if (!folderType) return false;\n return ['conf.d', 'config', 'completions'].includes(folderType);\n }\n\n /**\n * helper that gets the document URI if it is fish/functions directory\n */\n getAutoloadType(): AutoloadType {\n return this.getFolderType() || '';\n }\n\n /**\n * helper that gets the document URI if it is fish/functions directory\n * @returns {string} - what the function name should be, or '' if it is not autoloaded\n */\n getAutoLoadName(): string {\n if (!this.isAutoloadedUri()) {\n return '';\n }\n const parts = uriToPath(this.uri)?.split('/') || [];\n const name = parts[parts.length - 1];\n return name!.replace('.fish', '');\n }\n\n getFileName(): string {\n const items = uriToPath(this.uri).split('/') || [];\n const name = items.length > 0 ? items.pop()! : uriToPath(this.uri);\n return name;\n }\n\n getLines(): number {\n const lines = this.getText().split('\\n');\n return lines.length;\n }\n\n showTree(): void {\n logTreeSitterDocumentDebug(this);\n }\n\n getTree(): string {\n return returnParseTreeString(this);\n }\n\n updateVersion(version: number) {\n this.document = this.create(this.document.uri, this.document.languageId, version, this.document.getText());\n return this;\n }\n\n /**\n * Type guard to check if an object is an LspDocument\n *\n * @param value The value to check\n * @returns True if the value is an LspDocument, false otherwise\n */\n static is(value: unknown): value is LspDocument {\n return (\n // Check if it's an object first\n typeof value === 'object' &&\n value !== null &&\n // Check for LspDocument-specific methods/properties not found in TextDocument or TextDocumentItem\n typeof (value as LspDocument).asTextDocumentItem === 'function' &&\n typeof (value as LspDocument).asTextDocumentIdentifier === 'function' &&\n typeof (value as LspDocument).getAutoloadType === 'function' &&\n typeof (value as LspDocument).isAutoloaded === 'function' &&\n typeof (value as LspDocument).path === 'string' &&\n typeof (value as LspDocument).getFileName === 'function' &&\n typeof (value as LspDocument).getRelativeFilenameToWorkspace === 'function' &&\n typeof (value as LspDocument).getLine === 'function' &&\n typeof (value as LspDocument).getLines === 'function' &&\n // Ensure base TextDocument properties are also present\n typeof (value as LspDocument).uri === 'string' &&\n typeof (value as LspDocument).getText === 'function'\n );\n }\n\n /**\n * @TODO check that this correctly handles range creation for both starting and ending positions\n * If this doesn't work as expected, we could alternatively create the range manually with\n * `getRange(analyzedDocument.root)`\n */\n get fileRange(): Range {\n const start = Position.create(0, 0);\n const end = this.positionAt(this.getText().length);\n return Range.create(start, end);\n }\n\n hasShebang(): boolean {\n const firstLine = this.getLine(0);\n return firstLine.startsWith('#!');\n }\n}\n\n/**\n * A LineSpan represents a range of lines in a document that have changed.\n *\n * We use this later to optimize diagnostic updates, by comparing the changed\n * line span to the ranges of existing diagnostics, and removing any that\n * fall within the changed span.\n *\n * @property start - The starting line number (0-based).\n * @property end - The ending line number (0-based).\n * @property isFullDocument - If true, indicates the entire document changed.\n *\n * isFullDocument is optional and defaults to false, but is useful because\n * the consumer of this type, might want to treat actual isFullDocument changes\n * differently than incremental changes that would happen `documents.onDidChangeContent()`\n */\nexport type LineSpan = { start: number; end: number; isFullDocument?: boolean; };\n\n/**\n * Computes the span of lines that have changed in a set of TextDocumentContentChangeEvent.\n */\nfunction computeChangedLineSpan(\n changes: TextDocumentContentChangeEvent[],\n): LineSpan | undefined {\n if (changes.length === 0) return undefined;\n\n let start = Number.POSITIVE_INFINITY;\n let end = Number.NEGATIVE_INFINITY;\n\n for (const c of changes) {\n // Full-document sync\n if (TextDocumentContentChangeEvent.isFull(c)) {\n return { start: 0, end: Number.MAX_SAFE_INTEGER, isFullDocument: true };\n }\n\n // Incremental sync\n if (TextDocumentContentChangeEvent.isIncremental(c)) {\n const { range } = c as TextDocumentContentChangeEvent & { range: Range; };\n if (range.start.line < start) start = range.start.line;\n if (range.end.line > end) end = range.end.line;\n }\n }\n\n if (!Number.isFinite(start) || !Number.isFinite(end)) return undefined;\n return { start, end, isFullDocument: false };\n}\n\n// compare a Range to a LineSpan, with an optional offset (how many lines to expand the span by)\nexport function rangeOverlapsLineSpan(\n range: Range,\n span: { start: number; end: number; },\n offset: number = 1,\n): boolean {\n const safeOffset = Math.max(0, offset);\n\n // Expand the span by `offset` in both directions\n const expandedStart = Math.max(0, span.start - safeOffset);\n const expandedEnd = span.end + safeOffset;\n\n // Standard closed-interval overlap check:\n // [range.start.line, range.end.line] vs [expandedStart, expandedEnd]\n return range.start.line <= expandedEnd && range.end.line >= expandedStart;\n}\n\n/**\n * GLOBAL DOCUMENTS OBJECT (TextDocuments)\n *\n * This is now the canonical document manager, just like the VS Code sample,\n * but parameterized with our LspDocument wrapper.\n *\n * @example\n *\n * ```typescript\n * const documents = new TextDocuments(TextDocument);\n * ```\n */\nexport const documents = new TextDocuments({\n create: (uri, languageId, version, text) =>\n new LspDocument({ uri, languageId: languageId || 'fish', version, text }),\n update: (doc, changes, version) => {\n doc.update(changes, version);\n return doc;\n },\n});\n\nexport type Documents = typeof documents;\n"
},
{
"path": "src/documentation.ts",
"content": "import { dirname } from 'path';\nimport { SyntaxNode } from 'web-tree-sitter';\nimport { Hover, MarkupContent, MarkupKind } from 'vscode-languageserver-protocol/node';\nimport { execCommandDocs, execCommandType, CompletionArguments, execCompleteSpace, execCompleteCmdArgs, documentCommandDescription, execExpandBraceExpansion } from './utils/exec';\nimport { getChildNodes, getNodeText } from './utils/tree-sitter';\nimport { md } from './utils/markdown-builder';\nimport { Analyzer } from './analyze';\nimport { getExpandedSourcedFilenameNode } from './parsing/source';\nimport { isCommand, isOption } from './utils/node-types';\nimport { LspDocument } from './document';\nimport { uriToPath } from './utils/translation';\n\nexport type markdownFiletypes = 'fish' | 'man';\n\nexport function enrichToMarkdown(doc: string): MarkupContent {\n return {\n kind: MarkupKind.Markdown,\n value: [\n doc,\n ].join(),\n };\n}\n\nexport function enrichToCodeBlockMarkdown(doc: string, filetype: markdownFiletypes = 'fish'): MarkupContent {\n return {\n kind: MarkupKind.Markdown,\n value: [\n '```' + filetype,\n doc.trim(),\n '```',\n ].join('\\n'),\n };\n}\n\nexport function enrichWildcard(label: string, documentation: string, examples: [string, string][]): MarkupContent {\n const exampleStr: string[] = ['---'];\n for (const [cmd, desc] of examples) {\n exampleStr.push(`__${cmd}__ - ${desc}`);\n }\n return {\n kind: MarkupKind.Markdown,\n value: [\n `_${label}_ ${documentation}`,\n '---',\n exampleStr.join('\\n'),\n ].join('\\n'),\n };\n}\n\nexport function enrichCommandArg(doc: string): MarkupContent {\n const [_first, ...after] = doc.split('\\t');\n const first = _first?.trim() || '';\n const second = after?.join('\\t').trim() || '';\n\n const arg = '__' + first + '__';\n const desc = '_' + second + '_';\n const enrichedDoc = [\n arg,\n desc,\n ].join(' ');\n return enrichToMarkdown(enrichedDoc);\n}\n\nexport function enrichCommandWithFlags(command: string, description: string, flags: string[]): MarkupContent {\n const title = description ? `(${md.bold(command)}) ${description}` : md.bold(command);\n const flagLines = flags.map(line => line.split('\\t'))\n .map(line => `${md.bold(line.at(0)!)} ${md.italic(line.slice(1).join(' '))}`);\n\n const result: string[] = [];\n result.push(title);\n if (flags.length > 0) {\n result.push(md.separator());\n result.push(flagLines.join(md.newline()));\n }\n\n return enrichToMarkdown(result.join(md.newline()));\n}\n\nexport function handleSourceArgumentHover(analyzer: Analyzer, current: SyntaxNode, document?: LspDocument): Hover | null {\n // Get the base directory for resolving relative paths\n const baseDir = document ? dirname(uriToPath(document.uri)) : undefined;\n\n const sourceExpanded = getExpandedSourcedFilenameNode(current, baseDir);\n if (!sourceExpanded) return null;\n const sourceDoc = analyzer.getDocumentFromPath(sourceExpanded);\n if (!sourceDoc) {\n analyzer.analyzePath(sourceExpanded);\n }\n return {\n contents: enrichToMarkdown([\n `${md.boldItalic('SOURCE')} - ${md.italic('https://fishshell.com/docs/current/cmds/source.html')}`,\n md.separator(),\n `${md.codeBlock('fish', [\n 'source ' + current.text,\n sourceExpanded && sourceExpanded !== current.text ? `# source ${sourceExpanded}` : undefined,\n ].filter(Boolean).join('\\n'))}`,\n md.separator(),\n md.codeBlock('fish', sourceDoc!.getText()),\n ].join(md.newline())),\n };\n}\n\nexport async function handleBraceExpansionHover(current: SyntaxNode): Promise {\n let text = current.text;\n if (isOption(current) || isCommand(current)) {\n if (text.includes('=')) {\n text = text.slice(text.indexOf('=') + 1).trim();\n }\n }\n const expanded = await execExpandBraceExpansion(text);\n if (expanded.trim() === '' || expanded.trim() === '1 |``|') {\n return null; // No expansion found, return null\n }\n const isBraceExpansion = text.includes('{') && text.includes('}');\n const headerLines = isBraceExpansion ? [\n `${md.boldItalic('BRACE EXPANSION')} - ${md.italic('https://fishshell.com/docs/current/language.html#brace-expansion')}`,\n md.separator(),\n ] : [];\n return {\n contents: enrichToMarkdown([\n ...headerLines,\n md.codeBlock('fish', current.text),\n md.separator(),\n md.codeBlock('markdown', expanded),\n ].join(md.newline())),\n };\n}\n\nexport function handleEndStdinHover(current: SyntaxNode): Hover {\n return {\n contents: enrichToMarkdown([\n `(${md.boldItalic('END STDIN TOKEN')}) ${md.inlineCode(current.text)}`,\n md.separator(),\n [\n // TODO: decide on best wording for this documentation\n `The ${md.inlineCode('--')} token is used to denote that the command should ${md.bold('stop reading')} from ${md.inlineCode('/dev/stdin')} for ${md.italic('switches')}, and use the remaining ${md.inlineCode('$argv')} as ${md.italic('positional arguments')}.`,\n // '',\n // 'Useful when a command accepts switches and arguments that start with a dash (-).',\n // '',\n // `The ${md.boldItalic(`first`)} ${md.inlineCode('--')} ${md.boldItalic('argument')} that is not an option-argument should be accepted as a ${md.bold('delimiter')} indicating the ${md.bold('end of options')}.`,\n // '',\n // `Any ${md.bold('following arguments')} should be treated as operands, even if they begin with the ${md.bold('-')} character.`,\n // '',\n // md.codeBlock('fish', [\n // '# example pattern:',\n // 'utility_name [options] [--] [operands]'\n // ].join(md.newline())),\n ].join(md.newline()),\n md.separator(),\n md.codeBlock('fish', [\n '### EXAMPLES',\n '',\n '# 1. `argparse` considers `--help` as input and not an option (variable `_flag_help` is set)',\n 'argparse h/help -- --help',\n '',\n '# 2. `markdown_list` is joined without treating the \\'- .*\\' as options',\n 'set markdown_list (string join -- \\\\n \\'- first\\' \\'- second\\' \\'- third\\')',\n '',\n '# 3. `hasargs` checks if the arguments contains a -q option',\n 'function hasargs',\n ' if contains -- -q $argv',\n ' echo \\'$argv contains a -q option\\'',\n ' end',\n 'end',\n ].join('\\n')),\n ].join(md.newline())),\n };\n}\n\nexport function enrichToPlainText(doc: string): MarkupContent {\n return {\n kind: MarkupKind.PlainText,\n value: doc.trim(),\n };\n}\n\nexport async function documentationHoverProvider(cmd: string): Promise {\n const cmdDocs = await execCommandDocs(cmd);\n const cmdType = await execCommandType(cmd);\n\n if (!cmdDocs) {\n return null;\n } else {\n return {\n contents: cmdType === 'command'\n ? enrichToCodeBlockMarkdown(cmdDocs, 'man')\n : enrichToCodeBlockMarkdown(cmdDocs, 'fish'),\n };\n }\n}\n\nexport async function documentationHoverProviderForBuiltIns(cmd: string): Promise {\n const cmdDocs: string = await execCommandDocs(cmd);\n if (!cmdDocs) {\n return null;\n }\n const splitDocs = cmdDocs.split('\\n');\n const startIndex = splitDocs.findIndex((line: string) => line.trim() === 'NAME');\n return {\n contents: {\n kind: MarkupKind.Markdown,\n value: [\n `__${cmd.toUpperCase()}__ - _https://fishshell.com/docs/current/cmds/${cmd.trim()}.html_`,\n '___',\n '```man',\n splitDocs.slice(startIndex).join('\\n'),\n '```',\n ].join('\\n'),\n },\n };\n}\n\nfunction commandStringHelper(cmd: string) {\n const cmdArray = cmd.split(' ', 1);\n return cmdArray.length > 1\n ? '___' + cmdArray[0] + '___' + ' ' + cmdArray[1]\n : '___' + cmdArray[0] + '___';\n}\n\nexport function documentationHoverCommandArg(root: SyntaxNode, cmp: CompletionArguments): Hover {\n let text = '';\n const argsArray = [...cmp.args.keys()];\n for (const node of getChildNodes(root)) {\n const nodeText = getNodeText(node);\n if (nodeText.startsWith('-') && argsArray.includes(nodeText)) {\n text += '\\n' + '_' + nodeText + '_ ' + cmp.args.get(nodeText);\n }\n }\n const cmd = commandStringHelper(cmp.command.trim());\n return {\n contents:\n enrichToMarkdown(\n [\n cmd,\n '---',\n text.trim(),\n ].join('\\n'),\n ),\n };\n}\n\nexport function forwardSubCommandCollect(rootNode: SyntaxNode): string[] {\n const stringToComplete: string[] = [];\n for (const curr of rootNode.children) {\n if (curr.text.startsWith('-') && curr.text.startsWith('$')) {\n break;\n } else {\n stringToComplete.push(curr.text);\n }\n }\n return stringToComplete;\n}\n\nexport function forwardArgCommandCollect(rootNode: SyntaxNode): string[] {\n const stringToComplete: string[] = [];\n for (const curr of rootNode.children) {\n if (curr.text.startsWith('-') && curr.text.startsWith('$')) {\n stringToComplete.push(curr.text);\n } else {\n continue;\n }\n }\n return stringToComplete;\n}\n\nfunction getFlagString(arr: string[]): string {\n return '__' + arr[0] + '__' + ' ' + arr[1] + '\\n';\n}\n\nexport class HoverFromCompletion {\n private currentNode: SyntaxNode;\n\n private commandNode: SyntaxNode;\n private commandString: string = '';\n private entireCommandString: string = '';\n private completions: string[][] = [];\n private oldOptions: boolean = false;\n private flagsGiven: string[] = [];\n\n constructor(commandNode: SyntaxNode, currentNode: SyntaxNode) {\n this.currentNode = currentNode;\n this.commandNode = commandNode;\n this.commandString = commandNode.child(0)?.text || '';\n this.entireCommandString = commandNode.text || '';\n this.flagsGiven = this.entireCommandString\n .split(' ').slice(1)\n .filter(flag => flag.startsWith('-'))\n .map(flag => flag.split('=')[0]) as string[] || [];\n }\n\n /**\n * set this.commandString for possible subcommands\n * handles a command such as:\n * $ string match -ra '.*' -- \"hello all people\"\n */\n private async checkForSubCommands() {\n const spaceCmps = await execCompleteSpace(this.commandString);\n if (spaceCmps.length === 0) {\n return this.commandString;\n }\n const cmdArr = this.commandNode.text.split(' ').slice(1);\n let i = 0;\n while (i < cmdArr.length) {\n const argStr = cmdArr[i]!.trim();\n if (!argStr.startsWith('-') && spaceCmps.includes(argStr)) {\n this.commandString += ' ' + argStr.toString();\n } else if (argStr.includes('-')) {\n break;\n }\n i++;\n }\n return this.commandString;\n }\n\n private isSubCommand() {\n const currentNodeText = this.currentNode.text;\n if (currentNodeText.startsWith('-') || currentNodeText.startsWith(\"'\") || currentNodeText.startsWith('\"')) {\n return false;\n }\n const cmdArr = this.commandString.split(' ');\n if (cmdArr.length > 1) {\n return cmdArr.includes(currentNodeText);\n }\n return false;\n }\n\n /**\n * @see man complete: styles --> long options\n * enables the ability to differentiate between\n * short flags chained together, or a command\n * that\n * a command option like:\n * '-Wall' or --> returns true\n * find -name '.git' --> returns true\n *\n * ls -la --> returns false\n * @param {string[]} cmpFlags - [TODO:description]\n * @returns {boolean} true if old styles are valid\n * false if short flags can be chained\n */\n private hasOldStyleFlags() {\n for (const cmpArr of this.completions) {\n if (cmpArr[0]?.startsWith('--')) {\n continue;\n } else if (cmpArr[0]?.startsWith('-') && cmpArr[0]?.length > 2) {\n return true;\n }\n }\n return false;\n }\n\n /**\n * handles splitting short options if the command has no\n * old style flags.\n * @see this.hasOldStyleFlags()\n */\n private reparseFlags() {\n const shortFlagsHandled = [];\n for (const flag of this.flagsGiven) {\n if (flag.startsWith('--')) {\n shortFlagsHandled.push(flag);\n } else if (flag.startsWith('-') && flag.length > 2) {\n const splitShortFlags = flag.split('').slice(1).map(str => '-' + str);\n shortFlagsHandled.push(...splitShortFlags);\n }\n }\n return shortFlagsHandled;\n }\n\n public async buildCompletions() {\n this.commandString = await this.checkForSubCommands();\n const preBuiltCompletions = await execCompleteCmdArgs(this.commandString);\n for (const cmp of preBuiltCompletions) {\n this.completions.push(cmp.split('\\t'));\n }\n return this.completions;\n }\n\n public findCompletion(flag: string) {\n for (const flagArr of this.completions) {\n if (flagArr[0] === flag) {\n return flagArr;\n }\n }\n return null;\n }\n\n private async checkForHoverDoc() {\n const cmd = await documentCommandDescription(this.commandString);\n const cmdArr = cmd.trim().split(' ');\n const cmdStrLen = this.commandString.split(' ').length;\n const boldText = '__' + cmdArr.slice(0, cmdStrLen).join(' ') + '__';\n const otherText = ' ' + cmdArr.slice(cmdStrLen).join(' ');\n return boldText + otherText;\n }\n\n public async generateForFlags(): Promise {\n let text = '';\n this.completions = await this.buildCompletions();\n this.oldOptions = this.hasOldStyleFlags();\n const cmd = await this.checkForHoverDoc();\n if (!this.oldOptions) {\n this.flagsGiven = this.reparseFlags();\n }\n for (const flag of this.flagsGiven) {\n const found = this.findCompletion(flag);\n if (found) {\n text += getFlagString(found);\n }\n }\n return {\n contents: enrichToMarkdown([\n cmd,\n '---',\n text.trim(),\n ].join('\\n')),\n };\n }\n\n public async generateForSubcommand() {\n return await documentationHoverProvider(this.commandString);\n }\n\n public async generate(): Promise {\n this.commandString = await this.checkForSubCommands();\n if (this.isSubCommand()) {\n const output = await documentationHoverProvider(this.commandString);\n if (output) {\n return output;\n }\n } else {\n return await this.generateForFlags();\n }\n return;\n }\n}\n"
},
{
"path": "src/execute-handler.ts",
"content": "import { Connection } from 'vscode-languageserver';\nimport { exec } from 'child_process';\nimport { execAsyncFish } from './utils/exec';\nimport { promisify } from 'util';\nimport { appendFileSync } from 'fs';\nexport const execAsync = promisify(exec);\n\nexport type ExecResultKind = 'error' | 'info';\n\nexport type ExecResultWrapper = {\n message: string;\n kind: ExecResultKind;\n};\n\nexport async function execLineInBuffer(line: string): Promise {\n const { stderr, stdout } = await execAsync(`fish -c '${line}'; or true`);\n if (stderr) {\n return { message: buildOutput(line, 'stderr:', stderr), kind: 'error' };\n }\n if (stdout) {\n return { message: buildOutput(line, 'stdout:', stdout), kind: 'info' };\n }\n\n return {\n message: [\n `${fishLspPromptIcon} ${line}`,\n '-'.repeat(50),\n 'EMPTY RESULT',\n ].join('\\n'),\n kind: 'info',\n };\n}\n\nexport const fishLspPromptIcon = '><(((°>';\n\nexport function buildOutput(line: string, outputMessage: 'error:' | 'stderr:' | 'stdout:', output: string) {\n const tokens = line.trim().split(' ');\n let promptLine = `${fishLspPromptIcon} `;\n let currentLen = promptLine.length;\n for (const token of tokens) {\n if (1 + token.length + currentLen > 49) {\n const newToken = `\\\\\\n ${token} `;\n promptLine += newToken;\n currentLen = newToken.slice(newToken.indexOf('\\n')).length;\n } else {\n const newToken = token + ' ';\n promptLine += newToken;\n currentLen += newToken.length + 1;\n }\n }\n\n return [\n promptLine,\n '-'.repeat(50),\n `${outputMessage} ${output}`,\n ].join('\\n');\n}\n\nexport function buildExecuteNotificationResponse(\n input: string,\n output: { stdout: string; stderr: string; },\n) {\n const outputType = output.stdout ? output.stdout : output.stderr;\n const outputMessagePrefix = output.stdout ? 'stdout:' : 'stderr:';\n const kind: ExecResultKind = output.stdout ? 'info' : 'error';\n return {\n message: buildOutput(input, outputMessagePrefix, outputType),\n kind,\n };\n}\n\nexport async function execEntireBuffer(bufferName: string): Promise {\n const { stdout, stderr } = await execAsync(`fish ${bufferName}`);\n const statusOutput = (await execAsync(`fish -c 'fish ${bufferName} 1> /dev/null; echo \"\\\\$status: $status\"'`)).stdout;\n const headerOutput = [\n `${fishLspPromptIcon} executing file:`,\n `${' '.repeat(fishLspPromptIcon.length)} ${bufferName}`,\n ].join('\\n');\n\n const longestLineLen = findLongestLine(headerOutput, stdout, stderr, '-'.repeat(50)).length;\n let output = '';\n if (stdout) output += `${stdout}`;\n if (stdout && stderr) output += `\\nerror:\\n${stderr}`;\n else if (!stdout && stderr) output += `error:\\n${stderr}`;\n let messageType: ExecResultKind = 'info';\n\n if (stderr) messageType = 'error';\n\n if (statusOutput) output += `${'-'.repeat(longestLineLen)}\\n${statusOutput}`;\n\n return {\n message: [\n headerOutput,\n '-'.repeat(longestLineLen),\n output,\n ].join('\\n'),\n kind: messageType,\n };\n}\n\nexport async function sourceFishBuffer(bufferName: string) {\n const { stdout, stderr } = await execAsync(`fish -c 'source ${bufferName}'`);\n const statusOutput = (await execAsync(`fish -c 'source ${bufferName} 1> /dev/null; echo \"\\\\$status: $status\"'`)).stdout;\n const message = [\n `${fishLspPromptIcon} sourcing file:`,\n `${' '.repeat(fishLspPromptIcon.length)} ${bufferName}`,\n ].join('\\n');\n\n const longestLineLen = findLongestLine(message, stdout, stderr, statusOutput, '-'.repeat(50)).length;\n const outputArr: string[] = [];\n if (statusOutput) outputArr.push(statusOutput);\n if (stdout) outputArr.push(stdout);\n if (stderr) outputArr.push(stderr);\n\n const output = outputArr.join('-'.repeat(50) + '\\n');\n\n return [\n message,\n '-'.repeat(longestLineLen),\n output,\n ].join('\\n');\n}\n\nexport async function FishThemeDump() {\n return (await execAsyncFish('fish_config theme dump; or true')).stdout.split('\\n');\n}\n\nexport async function showCurrentTheme(buffName: string) {\n const output = (await execAsyncFish('fish_config theme demo; or true')).stdout.split('\\n');\n // Append the longest line to the file\n for (const line of output) {\n appendFileSync(buffName, `${line}\\n`, 'utf8');\n }\n return {\n message: `${fishLspPromptIcon} appended theme variables to end of file`,\n kind: 'info',\n };\n}\n\nexport type ThemeOptions = {\n asVariables: boolean;\n};\nconst defaultThemeOptions: ThemeOptions = {\n asVariables: false,\n\n};\n\nexport async function executeThemeDump(buffName: string, options: ThemeOptions = defaultThemeOptions): Promise {\n const output = (await execAsyncFish('fish_config theme dump; or true')).stdout.split('\\n');\n // Append the longest line to the file\n if (options.asVariables) {\n appendFileSync(buffName, '# created by fish-lsp');\n }\n for (const line of output) {\n if (options.asVariables) {\n appendFileSync(buffName, `set -gx ${line}\\n`, 'utf8');\n } else {\n appendFileSync(buffName, `${line}\\n`, 'utf8');\n }\n }\n return {\n message: `${fishLspPromptIcon} appended theme variables to end of file`,\n kind: 'info',\n };\n}\n\n/**\n * Function to find the longest line in a string.\n * @param input - The input string with lines separated by newline characters.\n * @returns The longest line in the input string.\n */\nfunction findLongestLine(...inputs: string[]): string {\n const input = inputs.join('\\n');\n // Split the input string by newline characters into an array of lines\n const lines: string[] = input.split('\\n');\n\n // Initialize a variable to keep track of the longest line\n let longestLine: string = '';\n\n // Iterate over each line\n for (const line of lines) {\n // If the current line is longer than the longestLine found so far, update longestLine\n if (line.length > longestLine.length) {\n longestLine = line;\n }\n }\n\n // Return the longest line found\n return longestLine;\n}\n\nexport function useMessageKind(connection: Connection, result: ExecResultWrapper) {\n switch (result.kind) {\n case 'info':\n connection.window.showInformationMessage(result.message);\n return;\n case 'error':\n connection.window.showErrorMessage(result.message);\n return;\n default:\n return;\n }\n}\n"
},
{
"path": "src/formatting.ts",
"content": "import { exec } from 'child_process';\nimport { logger } from './logger';\nimport { LspDocument } from './document';\nimport { getEnabledIndentRanges } from './parsing/comments';\n\nexport async function formatDocumentContent(content: string): Promise {\n return new Promise((resolve, _reject) => {\n const process = exec('fish_indent', (error, stdout, stderr) => {\n if (error) {\n // reject(stderr);\n logger.log('Formatting Error:', stderr);\n } else {\n resolve(stdout);\n }\n });\n if (process.stdin) {\n process.stdin.write(content);\n process.stdin.end();\n }\n });\n}\n\nexport async function formatDocumentRangeContent(content: string): Promise {\n return new Promise((resolve, _reject) => {\n const process = exec('fish_indent --only-indent --only-unindent', (error, stdout, stderr) => {\n if (error) {\n // reject(stderr);\n logger.log('Formatting Error:', stderr);\n } else {\n resolve(stdout);\n }\n });\n if (process.stdin) {\n process.stdin.write(content);\n process.stdin.end();\n }\n });\n}\n\ninterface OriginalRange {\n startMarker: string;\n endMarker: string;\n originalContent: string;\n originalStartComment: string;\n originalEndComment: string;\n}\n\nexport async function formatDocumentWithIndentComments(doc: LspDocument): Promise {\n const content = doc.getText();\n const formatRanges = getEnabledIndentRanges(doc);\n\n // If full document formatting is allowed, use regular formatting\n if (formatRanges.fullDocumentFormatting) {\n return formatDocumentContent(content);\n }\n\n const lines = content.split('\\n');\n\n // Step 1: Replace @fish_indent comments with position markers and collect original content\n const originalRanges: OriginalRange[] = [];\n let modifiedContent = '';\n let currentUnformattedContent = '';\n let isInUnformattedRange = false;\n let rangeId = 0;\n let currentStartMarker = '';\n let currentOriginalStartComment = '';\n\n for (let i = 0; i < lines.length; i++) {\n const line = lines[i];\n if (line === undefined || line === null) break;\n const trimmedLine = line.trim();\n const isIndentComment = /^#\\s*@fish_indent(?::\\s*(off|on)?)?$/.test(trimmedLine);\n const hasInlineIndentComment = /#\\s*@fish_indent(?::\\s*(off|on)?)?/.test(line);\n\n if (isIndentComment || hasInlineIndentComment) {\n // Extract the @fish_indent directive from either standalone or inline comment\n const match = isIndentComment\n ? trimmedLine.match(/^#\\s*@fish_indent(?::\\s*(off|on)?)?$/)\n : line.match(/#\\s*@fish_indent(?::\\s*(off|on)?)?/);\n const directive = match?.[1] || 'on'; // Default to 'on' if no directive specified\n\n if (directive === 'off' && !isInUnformattedRange) {\n // Start of unformatted range\n isInUnformattedRange = true;\n currentUnformattedContent = '';\n currentStartMarker = `# @fish_indent_marker_start_${rangeId}`;\n\n if (isIndentComment) {\n // Standalone comment - preserve the whole line as the comment\n currentOriginalStartComment = line;\n modifiedContent += currentStartMarker + '\\n';\n } else {\n // Inline comment - the code before the comment should be formatted\n const codeBeforeComment = line.substring(0, line.indexOf('#')).trimEnd();\n currentOriginalStartComment = '# @fish_indent: off'; // Store just the directive\n\n // Add the code part to formatted content, then start unformatted range\n modifiedContent += codeBeforeComment + '\\n';\n modifiedContent += currentStartMarker + '\\n';\n }\n } else if (directive === 'on' && isInUnformattedRange) {\n // End of unformatted range\n isInUnformattedRange = false;\n const endMarker = `# @fish_indent_marker_end_${rangeId}`;\n modifiedContent += endMarker + '\\n';\n\n if (!isIndentComment) {\n // Inline comment - add the code part after the marker\n const codeBeforeComment = line.substring(0, line.indexOf('#')).trimEnd();\n if (codeBeforeComment.trim()) {\n modifiedContent += codeBeforeComment + '\\n';\n }\n }\n\n originalRanges.push({\n startMarker: currentStartMarker,\n endMarker,\n originalContent: currentUnformattedContent,\n originalStartComment: currentOriginalStartComment,\n originalEndComment: isIndentComment ? line : '# @fish_indent: on',\n });\n\n rangeId++;\n } else {\n // Not a directive that changes state, treat as regular line\n if (isInUnformattedRange) {\n currentUnformattedContent += (currentUnformattedContent ? '\\n' : '') + line;\n } else {\n modifiedContent += line + '\\n';\n }\n }\n } else {\n if (isInUnformattedRange) {\n // Collect original content for later restoration\n currentUnformattedContent += (currentUnformattedContent ? '\\n' : '') + line;\n }\n // Always add the line to modifiedContent (it will be formatted if not in unformatted range)\n modifiedContent += line + '\\n';\n }\n }\n\n // Handle case where document ends with an unformatted range (missing @fish_indent: on)\n if (isInUnformattedRange) {\n const endMarker = `# @fish_indent_marker_end_${rangeId}`;\n modifiedContent += endMarker + '\\n';\n originalRanges.push({\n startMarker: currentStartMarker,\n endMarker,\n originalContent: currentUnformattedContent,\n originalStartComment: currentOriginalStartComment,\n originalEndComment: '', // No end comment if document ends with unformatted range\n });\n }\n\n // Step 2: Format the modified content with fish_indent\n const formattedContent = await formatDocumentContent(modifiedContent.trim());\n\n // Step 3: Restore original unformatted content between markers, including original comments\n let result = formattedContent;\n\n for (const range of originalRanges) {\n const startIndex = result.indexOf(range.startMarker);\n const endIndex = result.indexOf(range.endMarker);\n\n if (startIndex !== -1 && endIndex !== -1) {\n // Replace everything between (and including) the markers with original content\n const beforeMarker = result.substring(0, startIndex);\n const afterMarker = result.substring(endIndex + range.endMarker.length);\n\n // Reconstruct with original comments and content\n // Extract the indentation context from the formatted content around the markers\n const beforeLines = beforeMarker.split('\\n');\n const lastFormattedLine = beforeLines[beforeLines.length - 2] || ''; // Line before the marker\n\n const startIndentation = lastFormattedLine.match(/^(\\s*)/)?.[1] || '';\n\n // For the end comment, we need to determine what indentation level it should have\n // The end comment should maintain the same indentation level as the context it's in\n // In most cases, this should match the start comment's indentation since they're in the same block\n\n // However, we need to check if we're inside a function or other block structure\n // by looking at the original comment's indentation level\n const originalStartIndent = range.originalStartComment.match(/^(\\s*)/)?.[1] || '';\n\n // Use the original start comment's indentation level for the end comment\n // This preserves the user's intended structure\n const endIndentation = originalStartIndent;\n\n // Preserve the comment text but adjust indentation to match context\n // Extract original comment content without leading whitespace, but preserve trailing whitespace\n const startCommentText = range.originalStartComment.replace(/^\\s*/, '');\n const endCommentText = range.originalEndComment.replace(/^\\s*/, '');\n\n let replacement = startIndentation + startCommentText + '\\n';\n if (range.originalContent.trim()) {\n replacement += range.originalContent + '\\n';\n }\n if (endCommentText) {\n replacement += endIndentation + endCommentText;\n }\n\n result = beforeMarker + replacement + afterMarker;\n }\n }\n\n return result;\n}\n\nexport async function formatDocumentRangeWithIndentComments(\n doc: LspDocument,\n startLine: number,\n endLine: number,\n): Promise {\n // For range formatting, we need to use the same marker-based approach\n // but only apply it to the specific range requested\n\n // If the range doesn't intersect with any @fish_indent comments,\n // we can use a simpler approach\n const formatRanges = getEnabledIndentRanges(doc);\n\n if (formatRanges.fullDocumentFormatting) {\n // No @fish_indent comments, just format the range normally\n const content = doc.getText();\n const lines = content.split('\\n');\n const rangeLines = lines.slice(startLine, endLine + 1);\n const rangeContent = rangeLines.join('\\n');\n\n const formattedRangeContent = await formatDocumentContent(rangeContent);\n const formattedLines = [...lines];\n const newLines = formattedRangeContent.split('\\n');\n\n // Replace the range, handling potential line count changes\n formattedLines.splice(startLine, endLine - startLine + 1, ...newLines);\n\n return formattedLines.join('\\n');\n }\n\n // If there are @fish_indent comments, we need to format the entire document\n // using our marker approach, then extract only the requested range\n const fullFormattedContent = await formatDocumentWithIndentComments(doc);\n // const fullFormattedLines = fullFormattedContent.split('\\n');\n\n // Find the corresponding lines in the formatted content\n // This is tricky because line numbers may have changed due to fish_indent\n // For now, return the full formatted content (which preserves all functionality)\n // A more sophisticated approach would map the original range to the formatted range\n\n return fullFormattedContent;\n}\n"
},
{
"path": "src/hover.ts",
"content": "import * as LSP from 'vscode-languageserver';\nimport { Hover, MarkupKind } from 'vscode-languageserver-protocol/node';\nimport * as Parser from 'web-tree-sitter';\nimport { Analyzer } from './analyze';\nimport { LspDocument } from './document';\nimport { documentationHoverProvider, enrichCommandWithFlags, enrichToMarkdown } from './documentation';\nimport { DocumentationCache } from './utils/documentation-cache';\nimport { execCommandDocs, execCompletions, execSubCommandCompletions } from './utils/exec';\nimport { findParent, findParentCommand, isCommand, isFunctionDefinition, isOption, isProgram, isVariableDefinitionName, isVariableExpansion, isVariableExpansionWithName } from './utils/node-types';\nimport { findFirstParent, nodeLogFormatter } from './utils/tree-sitter';\nimport { symbolKindsFromNode, uriToPath } from './utils/translation';\nimport { logger } from './logger';\nimport { PrebuiltDocumentationMap } from './utils/snippets';\nimport { md } from './utils/markdown-builder';\nimport { AutoloadedPathVariables } from './utils/process-env';\n\nexport async function handleHover(\n analyzer: Analyzer,\n document: LspDocument,\n position: LSP.Position,\n current: Parser.SyntaxNode,\n cache: DocumentationCache,\n): Promise {\n if (isOption(current)) {\n return await getHoverForFlag(current);\n }\n const local = analyzer.getDefinition(document, position);\n logger.log({\n handleHover: handleHover.name,\n symbol: local?.name,\n position,\n current: nodeLogFormatter(current),\n });\n if (local) {\n return {\n contents: local.toMarkupContent(),\n range: local.selectionRange,\n };\n }\n const { kindType, kindString } = symbolKindsFromNode(current);\n const symbolType = ['function', 'class', 'variable'].includes(kindString) ? kindType : undefined;\n\n if (cache.find(current.text) !== undefined) {\n await cache.resolve(current.text, document.uri, symbolType);\n const item = symbolType ? cache.find(current.text, symbolType) : cache.getItem(current.text);\n if (item && item?.docs) {\n return {\n contents: {\n kind: MarkupKind.Markdown,\n value: item.docs.toString(),\n },\n };\n }\n }\n const commandString = await collectCommandString(current);\n\n const result = await documentationHoverProvider(commandString);\n logger.log({ handleHover: 'handleHover()', commandString, result });\n return result;\n}\n\nexport async function getHoverForFlag(current: Parser.SyntaxNode): Promise {\n const commandNode = findFirstParent(current, n => isCommand(n) || isFunctionDefinition(n));\n if (!commandNode) {\n return null;\n }\n let commandStr = [commandNode.child(0)?.text || ''];\n const flags: string[] = [];\n let hasFlags = false;\n for (const child of commandNode?.children || []) {\n if (!hasFlags && !child.text.startsWith('-')) {\n commandStr = await appendToCommand(commandStr, child.text);\n } else if (child.text.startsWith('-')) {\n flags.push(child.text);\n hasFlags = true;\n }\n }\n const flagCompletions = await execCompletions(...commandStr, '-');\n const shouldSplitShortFlags = hasOldUnixStyleFlags(flagCompletions);\n const fixedFlags = spiltShortFlags(flags, !shouldSplitShortFlags);\n const found = flagCompletions\n .map(line => line.split('\\t'))\n .filter(line => fixedFlags.includes(line[0] as string))\n .map(line => line.join('\\t'));\n\n /** find exact match for command */\n const prebuiltDocs = PrebuiltDocumentationMap.findMatchingNames(\n commandStr.join('-'),\n 'command',\n ).find(doc => doc.name === commandStr.join('-'));\n const description = !prebuiltDocs ? '' : prebuiltDocs?.description || '';\n return {\n contents: enrichCommandWithFlags(commandStr.join('-'), description, found),\n };\n}\n\nfunction hasOldUnixStyleFlags(allFlags: string[]) {\n for (const line of allFlags.map(line => line.split('\\t'))) {\n const flag = line[0] as string;\n if (flag.startsWith('-') && !flag.startsWith('--')) {\n if (flag.length > 2) {\n return true;\n }\n }\n }\n return false;\n}\n\nfunction spiltShortFlags(flags: string[], shouldSplit: boolean): string[] {\n const newFlags: string[] = [];\n for (let flag of flags) {\n flag = flag.split('=')[0] as string;\n if (flag.startsWith('-') && !flag.startsWith('--')) {\n if (flag.length > 2 && shouldSplit) {\n newFlags.push(...flag.split('').map(f => '-' + f));\n continue;\n }\n }\n newFlags.push(flag);\n }\n return newFlags;\n}\n\nasync function appendToCommand(commands: string[], subCommand: string): Promise {\n const completions = await execSubCommandCompletions(...commands, ' '); // HERE\n if (completions.includes(subCommand)) {\n commands.push(subCommand);\n return commands;\n } else {\n return commands;\n }\n}\n\nexport async function collectCommandString(current: Parser.SyntaxNode): Promise {\n const commandNode = findFirstParent(current, n => isCommand(n));\n if (!commandNode) {\n return '';\n }\n const commandNodeText = commandNode.child(0)?.text;\n const subCommandName = commandNode.child(1)?.text;\n if (subCommandName?.startsWith('-')) {\n return commandNodeText || '';\n }\n const commandText = [commandNodeText, subCommandName].join('-');\n const docs = await execCommandDocs(commandText);\n if (docs) {\n return commandText;\n }\n return commandNodeText || '';\n}\n\nconst allVariables = PrebuiltDocumentationMap.getByType('variable');\nexport function isPrebuiltVariableExpansion(node: Parser.SyntaxNode): boolean {\n if (isVariableExpansion(node)) {\n const variableName = node.text.slice(1);\n return allVariables.some(variable => variable.name === variableName);\n }\n return false;\n}\n\nexport function getPrebuiltVariableExpansionDocs(node: Parser.SyntaxNode): LSP.MarkupContent | null {\n if (isVariableExpansion(node)) {\n const variableName = node.text.slice(1);\n const variable = allVariables.find(variable => variable.name === variableName);\n if (variable) {\n return enrichToMarkdown([\n `(${md.italic('variable')}) - ${md.inlineCode('$' + variableName)}`,\n md.separator(),\n variable.description,\n ].join('\\n'));\n }\n }\n return null;\n}\n\nexport const variablesWithoutLocalDocumentation = [\n '$status',\n '$pipestatus',\n];\n\nexport function getVariableExpansionDocs(analyzer: Analyzer, doc: LspDocument, position: LSP.Position) {\n function isVariablesWithoutLocalDocumentation(current: Parser.SyntaxNode) {\n return variablesWithoutLocalDocumentation.includes('$' + current.text);\n }\n\n /**\n * Use this to append prebuilt documentation to variables with local documentation\n */\n function getPrebuiltVariableHoverContent(current: Parser.SyntaxNode): string | null {\n const docObject = allVariables.find(variable => variable.name === current.text);\n if (!docObject) return null;\n return [\n `(${md.italic('variable')}) ${md.bold(current.text)}`,\n md.separator(),\n docObject.description,\n ].join('\\n');\n }\n\n return function isPrebuiltExpansionDocsForVariable(current: Parser.SyntaxNode) {\n if (isVariableDefinitionName(current)) {\n const variableName = current.text;\n const parent = findParentCommand(current);\n if (AutoloadedPathVariables.has(variableName)) {\n return {\n contents: enrichToMarkdown(\n [\n AutoloadedPathVariables.getHoverDocumentation(variableName),\n md.separator(),\n md.codeBlock('fish', parent?.text || ''),\n ].join('\\n'),\n ),\n };\n }\n if (isVariablesWithoutLocalDocumentation(current)) {\n return {\n contents: enrichToMarkdown([\n getPrebuiltVariableHoverContent(current),\n md.separator(),\n md.codeBlock('fish', parent?.text || ''),\n ].join('\\n')),\n };\n }\n if (allVariables.find(variable => variable.name === current.text)) {\n return {\n contents: enrichToMarkdown([\n getPrebuiltVariableHoverContent(current),\n md.separator(),\n md.codeBlock('fish', parent?.text || ''),\n ].join('\\n')),\n };\n }\n return null;\n }\n if (current.type === 'variable_name' && current.parent && isVariableExpansion(current.parent)) {\n const variableName = current.text;\n if (AutoloadedPathVariables.has(variableName)) {\n return {\n contents: enrichToMarkdown(\n AutoloadedPathVariables.getHoverDocumentation(variableName),\n ),\n };\n }\n // argv\n const node = current.parent;\n if (isVariableExpansionWithName(node, 'argv')) {\n const parentNode = findParent(node, (n) => isProgram(n) || isFunctionDefinition(n)) as Parser.SyntaxNode;\n const variableName = node.text.slice(1);\n const variableDocObj = allVariables.find(variable => variable.name === variableName);\n if (isFunctionDefinition(parentNode)) {\n const functionName = parentNode.firstNamedChild!;\n return {\n contents: enrichToMarkdown([\n `(${md.italic('variable')}) ${md.bold('$argv')}`,\n `argument of function ${md.bold(functionName.text)}`,\n md.separator(),\n variableDocObj?.description,\n md.separator(),\n md.codeBlock('fish', parentNode.text),\n ].join('\\n')),\n };\n } else if (isProgram(parentNode)) {\n return {\n contents: enrichToMarkdown([\n `(${md.italic('variable')}) ${md.bold('$argv')}`,\n `arguments of script ${md.bold(uriToPath(doc.uri))}`,\n md.separator(),\n variableDocObj?.description,\n md.separator(),\n md.codeBlock('fish', parentNode.text),\n ].join('\\n')),\n };\n }\n } else if (variablesWithoutLocalDocumentation.includes(node.text)) {\n // status && pipestatus\n return { contents: getPrebuiltVariableExpansionDocs(node)! };\n } else if (!analyzer.getDefinition(doc, position) && isPrebuiltVariableExpansion(node)) {\n // variables which aren't defined in lsp's scope, but are documented\n const contents = getPrebuiltVariableExpansionDocs(node);\n if (contents) return { contents };\n }\n // consider enhancing variables with local documentation's, with their prebuilt documentation\n }\n return null;\n };\n}\n"
},
{
"path": "src/inlay-hints.ts",
"content": "import { InlayHint, InlayHintKind } from 'vscode-languageserver';\nimport { SyntaxNode } from 'web-tree-sitter';\nimport { PrebuiltDocumentationMap } from './utils/snippets';\nimport { isCommand, isCommandName, isReturn, isExit } from './utils/node-types';\nimport { findChildNodes } from './utils/tree-sitter';\nimport { Analyzer } from './analyze';\nimport { LspDocument } from './document';\nimport { getReferences } from './references';\nimport { logger } from './logger';\n\nexport function getStatusInlayHints(root: SyntaxNode): InlayHint[] {\n const hints: InlayHint[] = [];\n const returnStatements = findChildNodes(root, isReturn);\n const exitStatements = findChildNodes(root, isExit);\n\n for (const returnStmt of returnStatements) {\n const status = getReturnStatusValue(returnStmt);\n if (status) {\n hints.push({\n position: {\n line: returnStmt.endPosition.row,\n character: returnStmt.endPosition.column,\n },\n kind: InlayHintKind.Parameter,\n label: ` → ${status.inlineValue}`,\n paddingLeft: true,\n tooltip: {\n kind: 'markdown',\n value: `Status code ${status.tooltip.code}: ${status.tooltip.description}`,\n },\n });\n }\n }\n\n for (const exitStmt of exitStatements) {\n const status = getExitStatusValue(exitStmt);\n if (status) {\n hints.push({\n position: {\n line: exitStmt.endPosition.row,\n character: exitStmt.endPosition.column,\n },\n kind: InlayHintKind.Parameter,\n label: ` → ${status.inlineValue}`,\n paddingLeft: true,\n tooltip: {\n kind: 'markdown',\n value: `Exit code ${status.tooltip.code}: ${status.tooltip.description}`,\n },\n });\n }\n }\n\n return hints;\n}\n\nexport function findReturnNodes(root: SyntaxNode): SyntaxNode[] {\n const nodes: SyntaxNode[] = [];\n const queue = [root];\n\n while (queue.length > 0) {\n const node = queue.shift()!;\n if (isReturn(node)) {\n nodes.push(node);\n }\n queue.push(...node.children);\n }\n\n return nodes;\n}\n\nfunction getStatusDescription(status: string): string {\n const statusMap: Record = {\n 0: 'Success',\n 1: 'General error',\n 2: 'Misuse of shell builtins',\n 126: 'Command invoked cannot execute',\n 127: 'Command not found',\n 128: 'Invalid exit argument',\n 130: 'Script terminated by Control-C',\n };\n return statusMap[status] || `Exit code ${status}`;\n}\n\nexport function getReturnStatusValue(returnNode: SyntaxNode): {\n inlineValue: string;\n tooltip: {\n code: string;\n description: string;\n };\n} | undefined {\n const statusArg = returnNode.children.find(child =>\n !isCommand(child) && !isCommandName(child) && child.type === 'integer');\n\n if (!statusArg?.text) return undefined;\n\n const statusInfo = PrebuiltDocumentationMap.getByName(statusArg.text).pop();\n const statusInfoShort = getStatusDescription(statusArg.text);\n\n return statusInfoShort ? {\n inlineValue: statusInfoShort,\n tooltip: {\n code: statusInfo?.name || statusArg.text,\n description: statusInfo?.description || statusInfoShort,\n },\n } : undefined;\n}\n\nexport function getExitStatusValue(exitNode: SyntaxNode): {\n inlineValue: string;\n tooltip: {\n code: string;\n description: string;\n };\n} | undefined {\n const statusArg = exitNode.children.find(child =>\n !isCommand(child) && !isCommandName(child) && child.type === 'integer');\n\n if (!statusArg?.text) return undefined;\n\n const statusInfo = PrebuiltDocumentationMap.getByName(statusArg.text).pop();\n const statusInfoShort = getStatusDescription(statusArg.text);\n\n return statusInfoShort ? {\n inlineValue: statusInfoShort,\n tooltip: {\n code: statusInfo?.name || statusArg.text,\n description: statusInfo?.description || statusInfoShort,\n },\n } : undefined;\n}\n\n// Add a cache for the entire inlay hints result\ntype InlayHintsCache = {\n hints: InlayHint[];\n timestamp: number;\n version: number; // Track document version\n};\n\nconst inlayHintsCache = new Map();\nconst INLAY_HINTS_TTL = 1500; // 1.5 seconds TTL for full hints refresh\n\nfunction getCachedInlayHints(\n uri: string,\n documentVersion: number,\n): InlayHint[] | undefined {\n const entry = inlayHintsCache.get(uri);\n if (!entry) return undefined;\n\n // Return nothing if document version changed or cache is too old\n if (entry.version !== documentVersion ||\n Date.now() - entry.timestamp > INLAY_HINTS_TTL) {\n inlayHintsCache.delete(uri);\n return undefined;\n }\n\n return entry.hints;\n}\n\nfunction setCachedInlayHints(\n uri: string,\n hints: InlayHint[],\n documentVersion: number,\n) {\n inlayHintsCache.set(uri, {\n hints,\n timestamp: Date.now(),\n version: documentVersion,\n });\n}\n\nexport function getGlobalReferencesInlayHints(\n analyzer: Analyzer,\n document: LspDocument,\n): InlayHint[] {\n // Try to get cached hints first\n const cachedHints = getCachedInlayHints(document.uri, document.version);\n if (cachedHints) {\n logger?.log('Using cached inlay hints');\n return cachedHints;\n }\n\n logger?.log('Computing new inlay hints');\n\n const hints: InlayHint[] = analyzer.getFlatDocumentSymbols(document.uri)\n .filter(symbol => symbol.scope.scopeTag === 'global' || symbol.scope.scopeTag === 'universal')\n .map(symbol => {\n const referenceCount = getReferences(document, symbol.selectionRange.start).length;\n\n return {\n position: document.getLineEnd(symbol.selectionRange.start.line),\n kind: InlayHintKind.Type,\n label: `${referenceCount} reference${referenceCount === 1 ? '' : 's'}`,\n paddingLeft: true,\n tooltip: {\n kind: 'markdown',\n value: `${symbol.name} is referenced ${referenceCount} time${referenceCount === 1 ? '' : 's'} across the workspace`,\n },\n };\n });\n\n // Cache the new hints\n setCachedInlayHints(document.uri, hints, document.version);\n\n return hints;\n}\n\n// Function to invalidate cache when document changes\nexport function invalidateInlayHintsCache(uri: string) {\n inlayHintsCache.delete(uri);\n}\n\nexport function getAllInlayHints(analyzer: Analyzer, document: LspDocument): InlayHint[] {\n const results: InlayHint[] = [];\n const root = analyzer.getRootNode(document.uri);\n if (root) {\n results.push(...getStatusInlayHints(root));\n }\n return results;\n}\n"
},
{
"path": "src/linked-editing.ts",
"content": "import { LinkedEditingRanges, Position, Range } from 'vscode-languageserver';\nimport { LspDocument } from './document';\nimport { analyzer } from './analyze';\nimport { isFunctionDefinition, isStatement, isEnd } from './utils/node-types';\nimport { SyntaxNode } from 'web-tree-sitter';\n\n/**\n * Get linked editing ranges for a position in a document.\n * Returns ranges that should be edited together, such as:\n * - function keyword and end keyword in function definitions\n * - statement keywords (if, for, while, switch, begin) and their corresponding end keywords\n *\n * @param doc - The document to search\n * @param position - The position to check for linked editing ranges\n * @returns LinkedEditingRanges or null if no linked ranges found\n */\nexport function getLinkedEditingRanges(\n doc: LspDocument,\n position: Position,\n): LinkedEditingRanges | null {\n const current = analyzer.nodeAtPoint(doc.uri, position.line, position.character);\n\n if (!current) return null;\n\n // Find the parent statement or function definition\n let targetNode: SyntaxNode | null = null;\n let node: SyntaxNode | null = current;\n\n while (node) {\n if (isFunctionDefinition(node) || isStatement(node)) {\n targetNode = node;\n break;\n }\n node = node.parent;\n }\n\n if (!targetNode) return null;\n\n // Get the first and last children to find the opening and closing keywords\n const firstChild = targetNode.firstChild;\n const lastChild = targetNode.lastChild;\n\n if (!firstChild || !lastChild) return null;\n\n // Check that we have a proper block with 'end' keyword\n if (!isEnd(lastChild)) return null;\n\n const ranges: Range[] = [];\n\n // Add the opening keyword range (function, if, for, while, switch, begin)\n ranges.push(Range.create(\n doc.positionAt(firstChild.startIndex),\n doc.positionAt(firstChild.endIndex),\n ));\n\n // Add the end keyword range\n ranges.push(Range.create(\n doc.positionAt(lastChild.startIndex),\n doc.positionAt(lastChild.endIndex),\n ));\n\n return {\n ranges,\n };\n}\n"
},
{
"path": "src/logger.ts",
"content": "import * as console from 'node:console';\nimport fs from 'fs';\nimport { config } from './config';\n\nexport interface IConsole {\n error(...args: any[]): void;\n warn(...args: any[]): void;\n info(...args: any[]): void;\n debug(...args: any[]): void;\n log(...args: any[]): void;\n}\n\nexport const LOG_LEVELS = ['error', 'warning', 'info', 'debug', 'log', ''] as const;\nexport const DEFAULT_LOG_LEVEL: LogLevel = 'log';\n\nexport type LogLevel = typeof LOG_LEVELS[number];\nexport const LogLevel: Record = {\n error: 1,\n warning: 2,\n info: 3,\n debug: 4,\n log: 5,\n '': 6,\n};\n\nfunction getLogLevel(level: string): LogLevel {\n if (LOG_LEVELS.includes(level as LogLevel)) {\n return level as LogLevel;\n }\n return DEFAULT_LOG_LEVEL;\n}\n\nexport class Logger {\n /** The default console object */\n protected _console: IConsole = console;\n\n /** never print to console */\n private _silence: boolean = false;\n\n /** clear the log file once a log file has been set */\n private _clear: boolean = true;\n\n /** logs that were requested before a log file was set */\n private _logQueue: string[] = [];\n\n /** path to the log file */\n public logFilePath: string = '';\n\n /** set to true if the logger has been started */\n private started = false;\n\n /** set to true if the logger is connected to a server/client connection */\n private isConnectedToConnection = false;\n\n /** requires the server/client connection object to console.log() */\n private requiresConnectionConsole = true;\n\n /** set to true if the logger is connected to a server/client connection */\n private _logLevel: LogLevel = '';\n\n constructor(logFilePath: string = '') {\n this.logFilePath = logFilePath;\n\n // Bind methods to ensure proper this context\n this.log = this.log.bind(this);\n this.debug = this.debug.bind(this);\n this.info = this.info.bind(this);\n this.warning = this.warning.bind(this);\n this.error = this.error.bind(this);\n this._log = this._log.bind(this);\n this.convertArgsToString = this.convertArgsToString.bind(this);\n this._logWithSeverity = this._logWithSeverity.bind(this);\n this.logAsJson = this.logAsJson.bind(this);\n this.logFallbackToStdout = this.logFallbackToStdout.bind(this);\n }\n\n /**\n * Set the log file path\n */\n setLogFilePath(logFilePath: string): this {\n this.logFilePath = logFilePath;\n return this;\n }\n\n /**\n * Set the this._console to a connection.console and update the isConnectedToConnection property\n */\n setConnectionConsole(_console: IConsole | undefined): this {\n if (_console) {\n this._console = _console;\n this.isConnectedToConnection = true;\n }\n return this;\n }\n\n /**\n * Just set the console object, without changing the isConnectedToConnection property\n * This is useful for testing, with the requiresConnectionConsole property set to false\n */\n setConsole(_console: IConsole | undefined): this {\n if (_console) {\n this._console = _console;\n }\n return this;\n }\n\n setClear(clear: boolean = true): this {\n this._clear = clear;\n return this;\n }\n\n /**\n * Set the silence flag, so that console.log() will not be shown\n * This is used to make logging only appear in the log file.\n */\n setSilent(silence: boolean = true): this {\n this._silence = silence;\n return this;\n }\n\n /**\n * Set logLevel to a specific level\n */\n setLogLevel(level: string): this {\n const logLevel = getLogLevel(level);\n if (LOG_LEVELS.includes(logLevel)) {\n this._logLevel = logLevel;\n }\n return this;\n }\n\n /**\n * Allow using the default console object, instead of requiring the server to be connected to a server/client connection\n */\n allowDefaultConsole(): this {\n this.requiresConnectionConsole = false;\n return this;\n }\n\n isConnectionConsole(): boolean {\n return this.isConnectedToConnection;\n }\n\n isStarted(): boolean {\n return this.started;\n }\n\n isSilent(): boolean {\n return this._silence;\n }\n\n isClearing(): boolean {\n return this._clear;\n }\n\n isConnected(): boolean {\n return this.isConnectedToConnection && this.requiresConnectionConsole;\n }\n\n hasLogLevel(): boolean {\n return this._logLevel !== '';\n }\n\n hasConsole(): boolean {\n if (this.isConnectionConsole()) {\n return this.isConnected();\n }\n return this._console !== undefined;\n }\n\n start(): this {\n this.started = true;\n this.clearLogFile();\n this._logQueue.forEach((message) => {\n this._log(message);\n });\n return this;\n }\n\n hasLogFile(): boolean {\n return this.logFilePath !== '';\n }\n\n /**\n * Only clears the log file if this option has been enabled.\n */\n private clearLogFile(): void {\n if (this.isClearing() && this.hasLogFile()) {\n try {\n fs.writeFileSync(this.logFilePath, '');\n } catch (error) {\n this._console.error(`Error clearing log file: ${error}`);\n }\n }\n }\n\n /**\n * Converts arguments to a formatted string for logging\n * Handles various types of arguments with special handling for different types\n *\n * @param args - Arguments to convert to string\n * @returns Formatted string representation\n */\n convertArgsToString(...args: any[]): string {\n if (!args || args.length === 0) {\n return '';\n }\n\n // Format each argument appropriately\n const formattedArgs = args.map(arg => this.formatArgument(arg));\n\n // Join with newlines if multiple arguments\n return formattedArgs.length === 1\n ? formattedArgs.at(0) || ''\n : formattedArgs.join('\\n');\n }\n\n /**\n * Formats a single argument into a string representation\n *\n * @param arg - The argument to format\n * @returns Formatted string representation\n */\n private formatArgument(arg: any): string {\n // Handle null and undefined\n if (arg === null) return 'null';\n if (arg === undefined) return 'undefined';\n\n // Handle Error objects\n if (arg instanceof Error) {\n return arg.stack || arg.message || String(arg);\n }\n\n // Handle primitive types\n if (typeof arg === 'string') return arg;\n if (typeof arg !== 'object') return String(arg);\n\n // Handle Date objects\n if (arg instanceof Date) {\n return arg.toISOString();\n }\n\n // Handle Arrays specially for better readability\n if (Array.isArray(arg)) {\n if (arg.length === 0) return '[]';\n\n // For small arrays of primitives, format on one line\n if (arg.length < 5 && arg.every(item =>\n item === null ||\n item === undefined ||\n typeof item !== 'object')) {\n return JSON.stringify(arg);\n }\n }\n\n // Handle objects and arrays with circular reference protection\n try {\n const seen = new WeakSet();\n return JSON.stringify(arg, (key, value) => {\n // Skip functions\n if (typeof value === 'function') {\n return '[Function]';\n }\n\n // Handle RegExp\n if (value instanceof RegExp) {\n return value.toString();\n }\n\n // Skip circular references\n if (typeof value === 'object' && value !== null) {\n if (seen.has(value)) {\n return '[Circular Reference]';\n }\n seen.add(value);\n }\n return value;\n }, 2);\n } catch (err) {\n // Fallback in case of JSON.stringify failure\n try {\n const className = arg.constructor?.name || 'Object';\n const properties = Object.keys(arg).length > 0\n ? `with ${Object.keys(arg).length} properties`\n : 'empty';\n return `[${className}: ${properties}]`;\n } catch {\n return '[Object: stringify failed]';\n }\n }\n }\n\n private _log(...args: any[]): void {\n if (!args) return;\n if (!this.isSilent() && this.hasConsole()) this._console.log(...args);\n const formattedMessage = this.convertArgsToString(...args);\n if (this.hasLogFile()) {\n fs.appendFileSync(this.logFilePath, formattedMessage + '\\n', 'utf-8');\n } else {\n this._logQueue.push(formattedMessage);\n }\n }\n\n public logAsJson(...args: any[]) {\n if (!args || args.some(arg => !arg)) return;\n const formattedMessage = this.convertArgsToString(args);\n this._log({\n date: new Date().toLocaleString(),\n message: formattedMessage,\n });\n }\n\n private _logWithSeverity(severity: LogLevel, ...args: string[]): void {\n if (this.hasLogLevel() && LogLevel[this._logLevel] < LogLevel[severity]) {\n return;\n }\n const formattedMessage = [severity.toUpperCase() + ':', this.convertArgsToString(...args)].join(' ');\n this._log(formattedMessage);\n }\n\n logPropertiesForEachObject>(objs: T[], ...keys: (keyof T)[]): void {\n objs.forEach((obj, i) => {\n // const selectedKeys = keys.filter(key => obj.hasOwnProperty(key));\n const selectedKeys = keys.filter(key => Object.prototype.hasOwnProperty.bind(obj, key));\n const selectedObj = selectedKeys.reduce((acc, key) => {\n acc[key] = obj[key];\n return acc;\n }, {} as Partial);\n\n const formattedMessage = `${i}: ${JSON.stringify(selectedObj, null, 2)}`;\n this._log(formattedMessage);\n });\n }\n\n public logTime(...args: any[]): void {\n const formattedMessage = this.convertArgsToString(...args);\n const time = new Date().toLocaleTimeString();\n this._log(`[${time}] ${formattedMessage}`);\n }\n\n public log(...args: any[]): void {\n if (!args) return;\n const formattedMessage = this.convertArgsToString(...args);\n if (!this.hasLogLevel()) {\n this._log(formattedMessage);\n return;\n }\n this._logWithSeverity('log', formattedMessage);\n }\n\n public debug(...args: any[]): void {\n this._logWithSeverity('debug', ...args);\n }\n\n public info(...args: any[]): void {\n this._logWithSeverity('info', ...args);\n }\n\n public warning(...args: any[]): void {\n this._logWithSeverity('warning', ...args);\n }\n\n public error(...args: any[]): void {\n this._logWithSeverity('error', ...args);\n }\n\n /**\n * Util for logging to stdout, with optional trailing newline.\n * Will not include any logs that are passed in to the logger.\n * @param message - the message to log\n * @param newline - whether to add a trailing newline\n */\n public logToStdout(message: string, newline = true): void {\n const newlineChar = newline ? '\\n' : '';\n const output: string = `${message}${newlineChar}`;\n process.stdout.write(output);\n }\n\n /**\n * Util for joining multiple strings and logging to stdout with trailing `\\n`\n * Will not include any logs that are passed in to the logger.\n */\n public logToStdoutJoined(...message: string[]): void {\n const output: string = `${message.join('')}\\n`;\n process.stdout.write(output);\n }\n\n public logToStderr(message: string, newline = true): void {\n const output: string = `${message}${!!newline && '\\n'}`;\n process.stderr.write(output);\n }\n\n /**\n * A helper function to wrap default logging behavior for the logger, if it is started.\n * - If logger is started, log to logger `logger.log()`\n * - If logger is not started, log to stdout `logToStdout()`\n *\n * @param args - any number of arguments to log\n * @returns void\n */\n public logFallbackToStdout(...args: any[]): void {\n if (this.isStarted()) {\n this.log(...args);\n } else {\n this.logToStdout(JSON.stringify(args, null, 2), true);\n }\n }\n}\n\nexport function now(): string {\n const currentTime = new Date();\n const hours = currentTime.getHours();\n const hour12 = hours % 12 || 12;\n const ampm = hours >= 12 ? 'PM' : 'AM';\n\n return [\n hour12.toString().padStart(2, '0'),\n currentTime.getMinutes().toString().padStart(2, '0'),\n currentTime.getSeconds().toString().padStart(2, '0'),\n Math.floor(currentTime.getMilliseconds() / 10).toString().padStart(2, '0'),\n ].join(':') + ` ${ampm}`;\n}\n\nexport const logger: Logger = new Logger();\n\nexport function createServerLogger(logFilePath: string, connectionConsole?: IConsole): Logger {\n return logger\n .setLogFilePath(logFilePath)\n .setConnectionConsole(connectionConsole)\n .setSilent()\n .setLogLevel(config.fish_lsp_log_level as LogLevel)\n .start();\n}\n"
},
{
"path": "src/main.ts",
"content": "#!/usr/bin/env node\n\n// Enable source map support for better stack traces\nimport 'source-map-support/register';\n\n// Universal entry point for fish-lsp that handles CLI, Node.js module, and browser usage\n// This single file replaces the need for separate entry points and wrappers\n\n// Import polyfills for compatibility\nimport './utils/polyfills';\n\n// Initialize virtual filesystem first (must be before any fs operations)\nimport './virtual-fs';\n\nimport './utils/commander-cli-subcommands';\nimport { execCLI } from './cli';\n\n// Environment detection\nfunction isBrowserEnvironment(): boolean {\n return typeof window !== 'undefined' || typeof self !== 'undefined';\n}\n\nfunction isRunningAsCLI(): boolean {\n return !isBrowserEnvironment() && require.main === module;\n}\n\n// CLI functionality - only load when needed\nasync function runCLI() {\n execCLI();\n}\n\n// Import web module to ensure it's bundled and can auto-initialize\nimport './web';\n\n// Export both Node.js and web versions\nexport { default as FishServer } from './server';\nexport { FishLspWeb } from './web';\nexport { setExternalConnection, createConnectionType } from './utils/startup';\nexport type { ConnectionType, ConnectionOptions } from './utils/startup';\n\n// Default export for CommonJS compatibility\nimport FishServer from './server';\nexport default FishServer;\n\n// Auto-initialization based on environment\nif (isBrowserEnvironment()) {\n // Browser environments are auto-initialized by web.ts itself\n // No need to do anything here\n} else if (isRunningAsCLI() || process.env.NODE_ENV === 'test') {\n // Auto-run CLI if this file is executed directly\n runCLI().catch(async (error) => {\n const { logger } = await import('./logger');\n logger.logToStderr(`Failed to start fish-lsp CLI: ${error}`);\n process.exit(1);\n });\n}\n"
},
{
"path": "src/parser.ts",
"content": "import Parser from 'web-tree-sitter';\nimport treeSitterWasmPath from 'web-tree-sitter/tree-sitter.wasm';\nimport fishLanguageWasm from '@esdmr/tree-sitter-fish/tree-sitter-fish.wasm';\nimport { logger } from './logger';\n\nconst _global: any = global;\n\nexport async function initializeParser(): Promise {\n if (_global.fetch) {\n delete _global.fetch;\n }\n if (!_global.Module) {\n _global.Module = {\n onRuntimeInitialized: () => { },\n instantiateWasm: undefined,\n locateFile: undefined,\n wasmBinary: undefined,\n };\n }\n\n // treeSitterWasmPath is already a Uint8Array from the esbuild plugin\n // which reads web-tree-sitter/tree-sitter.wasm and embeds it\n const tsWasmBuffer = bufferToUint8Array(treeSitterWasmPath);\n\n // Initialize Parser with embedded WASM binary\n await Parser.init({\n wasmBinary: tsWasmBuffer,\n });\n\n const parser = new Parser();\n const fishWasmBuffer = bufferToUint8Array(fishLanguageWasm); // \\0asm\n\n try {\n const lang = await Parser.Language.load(fishWasmBuffer);\n parser.setLanguage(lang);\n } catch (error) {\n logger.logToStderr('Failed to load fish language grammar for tree-sitter parser.');\n console.error('Error loading fish language grammar:', error);\n throw error;\n }\n\n return parser;\n}\n\nfunction bufferToUint8Array(buffer: ArrayBuffer | Buffer | string): Uint8Array {\n if (typeof buffer === 'string' && buffer.startsWith('data:application/wasm;base64,')) {\n const base64Data = buffer.replace('data:application/wasm;base64,', '');\n return Buffer.from(base64Data, 'base64');\n } else if (typeof buffer === 'string') {\n return Buffer.from(buffer, 'base64');\n } else {\n return buffer as Uint8Array;\n }\n}\n"
},
{
"path": "src/parsing/alias.ts",
"content": "import { SyntaxNode } from 'web-tree-sitter';\nimport { FishSymbol } from './symbol';\nimport { DefinitionScope, getScope } from '../utils/definition-scope';\nimport { LspDocument } from '../document';\nimport { getRange } from '../utils/tree-sitter';\nimport { findParentWithFallback, isCommandWithName, isConcatenation, isFunctionDefinition, isString, isTopLevelDefinition } from '../utils/node-types';\nimport { isBuiltin } from '../utils/builtins';\nimport { md } from '../utils/markdown-builder';\nimport { flattenNested } from '../utils/flatten';\n\nexport type FishAliasInfoType = {\n name: string;\n value: string;\n prefix: 'builtin' | 'command' | '';\n wraps: string | null;\n hasEquals: boolean;\n};\n\nexport namespace FishAlias {\n\n /**\n * Checks if a node is an alias command.\n */\n export function isAlias(node: SyntaxNode): boolean {\n return isCommandWithName(node, 'alias');\n }\n\n /**\n * Extracts the alias name and value from a SyntaxNode representing an alias command.\n * Handles both formats:\n * - alias name=value\n * - alias name value\n */\n export function getInfo(node: SyntaxNode): {\n name: string;\n value: string;\n prefix: 'builtin' | 'command' | '';\n wraps: string | null;\n hasEquals: boolean;\n } | null {\n if (!isCommandWithName(node, 'alias')) return null;\n\n const firstArg = node.firstNamedChild?.nextNamedSibling;\n if (!firstArg) return null;\n\n let name: string;\n let value: string;\n let hasEquals: boolean;\n\n // Handle both alias formats\n if (firstArg.text.includes('=')) {\n // Format: alias name=value\n const [nameStr, ...valueParts] = firstArg.text.split('=');\n // Return null if name or value is empty\n if (!nameStr || valueParts.length === 0) return null;\n\n name = nameStr;\n value = valueParts.join('=').replace(/^['\"]|['\"]$/g, '');\n hasEquals = true;\n } else {\n // Format: alias name value\n const valueNode = firstArg.nextNamedSibling;\n if (!valueNode) return null;\n\n name = firstArg.text;\n value = valueNode.text.replace(/^['\"]|['\"]$/g, '');\n hasEquals = false;\n }\n\n // Determine prefix for recursive command prevention\n const words = value.split(/\\s+/);\n const firstWord = words.at(0);\n const lastWord = words.at(-1);\n\n // Determine prefix for recursive command prevention\n let prefix: 'builtin' | 'command' | '' = '';\n if (firstWord === name) {\n prefix = isBuiltin(name) ? 'builtin' : 'command';\n }\n\n // Determine if we should include wraps\n // Do not wrap if alias foo 'foo xyz' or alias foo 'sudo foo'\n const shouldWrap = firstWord !== name && lastWord !== name;\n const wraps = shouldWrap ? value : null;\n\n return {\n name,\n value,\n prefix,\n wraps,\n hasEquals,\n };\n }\n\n /**\n * Converts a SyntaxNode representing an alias command into a function definition.\n * The function definition includes:\n * - function name\n * - optional --wraps flag\n * - description\n * - function body\n */\n export function toFunction(node: SyntaxNode): string | null {\n const aliasInfo = getInfo(node);\n if (!aliasInfo) return null;\n\n const { name, value, prefix, wraps, hasEquals } = aliasInfo;\n\n // Escape special characters in the value for both the wraps and description\n const escapedValue = value.replace(/\\\\/g, '\\\\\\\\').replace(/'/g, \"\\\\'\");\n\n // Build the description string that matches fish's alias format\n const description = hasEquals ?\n `alias ${name}=${escapedValue}` :\n `alias ${name} ${escapedValue}`;\n\n // Build the function components\n const functionParts = [\n `function ${name}`,\n wraps ? `--wraps='${escapedValue}'` : '',\n `--description '${description}'`,\n ].filter(Boolean).join(' ');\n\n // Build the function body with optional prefix\n const functionBody = prefix ?\n ` ${prefix} ${value} $argv` :\n ` ${value} $argv`;\n\n // Combine all parts\n return [\n functionParts,\n functionBody,\n 'end',\n ].join('\\n');\n }\n\n export function getNameRange(node: SyntaxNode) {\n const aliasInfo = getInfo(node);\n if (!aliasInfo) return null;\n const nameNode = node.firstNamedChild?.nextNamedSibling;\n if (!nameNode) return null;\n if (!aliasInfo.hasEquals) {\n return getRange(nameNode);\n }\n const nameLength = aliasInfo.name.length;\n return {\n start: {\n line: nameNode.startPosition.row,\n character: nameNode.startPosition.column,\n },\n end: {\n line: nameNode.endPosition.row,\n character: nameNode.startPosition.column + nameLength,\n },\n };\n }\n\n export function buildDetail(node: SyntaxNode) {\n const aliasInfo = getInfo(node);\n\n if (!aliasInfo) return null;\n const { name } = aliasInfo;\n\n const detail = toFunction(node);\n if (!detail) return null;\n\n return [\n `(${md.italic('alias')}) ${name}`,\n md.separator(),\n md.codeBlock('fish', node.text),\n md.separator(),\n md.codeBlock('fish', detail),\n ].join('\\n');\n }\n\n export function toFishDocumentSymbol(\n child: SyntaxNode,\n parent: SyntaxNode,\n document: LspDocument,\n children: FishSymbol[] = [],\n ): FishSymbol | null {\n const aliasInfo = getInfo(parent);\n if (!aliasInfo) return null;\n\n const { name } = aliasInfo;\n const detail = toFunction(parent);\n if (!detail) return null;\n\n const selectionRange = getNameRange(parent);\n if (!selectionRange) return null;\n\n const detailText = buildDetail(parent);\n if (!detailText) return null;\n\n return FishSymbol.fromObject({\n name,\n document,\n uri: document.uri,\n node: parent,\n focusedNode: child,\n detail: detailText,\n fishKind: 'ALIAS',\n range: getRange(parent),\n selectionRange,\n scope: getScope(document, child),\n children,\n });\n }\n}\n\nfunction getAliasScopeModifier(document: LspDocument, node: SyntaxNode) {\n const autoloadType = document.getAutoloadType();\n switch (autoloadType) {\n case 'conf.d':\n case 'config':\n return isTopLevelDefinition(node) ? 'global' : 'local';\n case 'functions':\n return 'local';\n default:\n return 'local';\n }\n}\n\nfunction getScopeNode(node: SyntaxNode) {\n if (node.parent) return node.parent;\n return findParentWithFallback(node, isFunctionDefinition);\n}\n\n/**\n * TODO: remove this function from ../utils/node-types.ts `isAliasName`\n * checks if a node is the firstNamedChild of an alias command\n *\n * alias ls='ls -G'\n * ^-- cursor is here\n *\n * alias cls 'command ls'\n * ^-- cursor is here\n */\nexport function isAliasDefinitionName(node: SyntaxNode) {\n if (isString(node) || isConcatenation(node)) return false;\n if (!node.parent) return false;\n // concatenated node is an alias with `=`\n const isConcatenated = isConcatenation(node.parent);\n // if the parent is a concatenation node, then move up to it's parent\n let parentNode = node.parent;\n // if that is the case, then we need to move up 1 more parent\n if (isConcatenated) parentNode = parentNode.parent as SyntaxNode;\n if (!parentNode || !isCommandWithName(parentNode, 'alias')) return false;\n // since there is two possible cases, handle concatenated and non-concatenated differently\n const firstChild = isConcatenated\n ? parentNode.firstNamedChild\n : parentNode.firstChild;\n // skip `alias` named node, since it's not the alias name\n if (firstChild && firstChild.equals(node)) return false;\n const args = parentNode.childrenForFieldName('argument');\n // first element is args is the alias name\n const aliasName = isConcatenated\n ? args.at(0)?.firstChild\n : args.at(0);\n return !!aliasName && aliasName.equals(node);\n}\n\nexport function isAliasDefinitionValue(node: SyntaxNode) {\n if (!node.parent) return false;\n // concatenated node is an alias with `=`\n const isConcatenated = isConcatenation(node.parent);\n // if the parent is a concatenation node, then move up to it's parent\n let parentNode = node.parent;\n // if that is the case, then we need to move up 1 more parent\n if (isConcatenated) parentNode = parentNode.parent as SyntaxNode;\n if (!parentNode || !isCommandWithName(parentNode, 'alias')) return false;\n // since there is two possible cases, handle concatenated and non-concatenated differently\n const firstChild = isConcatenated\n ? parentNode.firstNamedChild?.nextNamedSibling\n : parentNode.firstChild;\n // skip `alias` named node, since it's not the alias name\n if (firstChild && firstChild.equals(node)) return false;\n const args = flattenNested(...parentNode.childrenForFieldName('argument'))\n .filter(a => a.isNamed);\n\n // first element is args is the alias name\n // logger.debug('alias args', args.map(a => a.text));\n const aliasValue = args.at(-1);\n return !!aliasValue && aliasValue.equals(node);\n}\n\nexport function processAliasCommand(document: LspDocument, node: SyntaxNode, children: FishSymbol[] = []) {\n const modifier = getAliasScopeModifier(document, node);\n const scopeNode = getScopeNode(node);\n const definitionNode = node.firstNamedChild!;\n const info = FishAlias.getInfo(node);\n const detail = FishAlias.buildDetail(node);\n const nameRange = FishAlias.getNameRange(node);\n if (!info || !detail) return [];\n return [\n FishSymbol.fromObject({\n name: info.name,\n node,\n focusedNode: definitionNode,\n range: getRange(node),\n selectionRange: nameRange || getRange(definitionNode),\n fishKind: 'ALIAS',\n document,\n uri: document.uri,\n detail,\n scope: DefinitionScope.create(scopeNode, modifier),\n children,\n }),\n ];\n}\n"
},
{
"path": "src/parsing/argparse.ts",
"content": "import path, { dirname } from 'path';\nimport { SyntaxNode } from 'web-tree-sitter';\nimport { FishSymbol } from './symbol';\nimport { LspDocument } from '../document';\nimport { analyzer } from '../analyze';\nimport { getRange } from '../utils/tree-sitter';\nimport { DefinitionScope, ScopeTag } from '../utils/definition-scope';\nimport { findOptions, isMatchingOption, Option } from './options';\nimport { isCommandWithName, isEndStdinCharacter, isString, isEscapeSequence, isVariableExpansion, isCommand, isInvalidVariableName, findParentWithFallback, isFunctionDefinition, isOption } from '../utils/node-types';\nimport { SyncFileHelper } from '../utils/file-operations';\nimport { pathToUri, uriToPath } from '../utils/translation';\nimport { workspaceManager } from '../utils/workspace-manager';\nimport { logger } from '../logger';\n\nexport const ArgparseOptions = [\n Option.create('-n', '--name').withValue(),\n Option.create('-x', '--exclusive').withValue(),\n Option.create('-N', '--min-args').withValue(),\n Option.create('-X', '--max-args').withValue(),\n Option.create('-U', '--move-unknown'),\n Option.create('-S', '--strict-longopts'),\n Option.long('--unknown-arguments').withValue(),\n Option.create('-i', '--ignore-unknown'),\n Option.create('-s', '--stop-nonopt'),\n Option.create('-h', '--help'),\n];\n\nconst ArgparseOptsWithValues = ArgparseOptions.filter(opt =>\n opt.equalsRawOption('-n', '--name') ||\n opt.equalsRawOption('-x', '--exclusive') ||\n opt.equalsRawOption('-N', '--min-args') ||\n opt.equalsRawOption('-X', '--max-args') ||\n opt.equalsRawOption('--unknown-arguments'),\n);\n\nconst isBefore = (a: SyntaxNode, b: SyntaxNode) => a.startIndex < b.startIndex;\n\nexport function findArgparseOptions(node: SyntaxNode) {\n if (isCommandWithName(node, 'argparse')) return undefined;\n const endChar = node.children.find(node => isEndStdinCharacter(node));\n if (!endChar) return undefined;\n const nodes = node.childrenForFieldName('argument')\n .filter(n => !isEscapeSequence(n) && isBefore(n, endChar))\n .filter(n => !isVariableExpansion(n) || n.type !== 'variable_name');\n return findOptions(nodes, ArgparseOptions);\n}\n\n/**\n * Utility to ensure that args for `argparse` option variable definitions exclude\n * argparse's optspec nodes, which can be in the form of:\n * • `-n foo`, `--name foo`\n * • `-x g,U`, `--exclusive=g,U`\n * • `--ignore-unknown`, `--stop-nonopt`\n * • `--unknown-arguments=KIND`\n * • `-N 1`, `--min-args=1` , `--max-args=2` , '-X 2'\n *\n * Backtrack using the current node, to check if the previous node is an `argparse` switch\n * that would inidicate the current node is a value for that switch, and\n * should not be included as an `argparse` definition name.\n *\n * @example\n * ```fish\n * argparse -n=foo -x g,U --ignore-unknown --stop-nonopt h/help 'n/name=?' 'x/exclusive' -- $argv\n * # ^^^^^^ ^^ ^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^ skipped via (check 1)\n * # ^^^ skipped via (check 2)\n * ```\n */\nfunction isArgparseOptionSpecifier(node: SyntaxNode) {\n // Check 1\n if (isOption(node)) return true;\n\n // Check 2\n const previousNode = node.previousSibling;\n if (!previousNode) return false;\n\n // we return false here to indicate that we should not skip this node\n // because the value for the previous node was provided using `--flag=value` syntax\n if (previousNode.text.includes('=')) return false;\n\n // don't skip previous nodes when the previous node is of the form:\n // ```fish\n // argparse -N 1 --max-args 2\n // # ^ ^\n // # Both of these nodes are excluded\n // ```\n return ArgparseOptsWithValues.some((option) => isMatchingOption(previousNode, option));\n // return isMatchingOption(previousNode, Option.create('-n', '--name')) ||\n // isMatchingOption(previousNode, Option.create('-x', '--exclusive')) ||\n // isMatchingOption(previousNode, Option.create('-N', '--min-args')) ||\n // isMatchingOption(previousNode, Option.create('-X', '--max-args')) ||\n // isMatchingOption(previousNode, Option.long('--unknown-arguments'))\n}\n\nfunction isInvalidArgparseName(node: SyntaxNode) {\n if (isEscapeSequence(node) || isCommand(node) || isInvalidVariableName(node)) return true;\n if (isArgparseOptionSpecifier(node)) return true;\n if (isVariableExpansion(node) || node.type === 'variable_name') return true;\n // fixup the text, so we ignore '/\" characters surrounding the flag names,\n let text = node.text.trim();\n if (isString(node)) {\n text = text.slice(1, -1);\n }\n // ignore anything after an `=` character since that would not be part of the variable name\n text = text.slice(0, text.indexOf('=') || -1);\n // incase parser missed one of these cases, we do a final check to see if the text includes\n // any characters that would be invalid for an argparse variable definition\n // (e.g., command substitutions, variable expansions)\n if (text.includes('(') || text.includes('$')) return true;\n return false;\n}\n\n/**\n * Find the names of the `argparse` definitions in a given node.\n * Example:\n * argparse -n foo -x g,U --ignore-unknown --stop-nonopt h/help 'n/name=?' 'x/exclusive' -- $argv\n * ^^^^^^ ^^^^^^^^^ ^^^^^^^^^^^^^\n * Notice that the nodes that are matches can be strings\n *\n *\n */\nexport function findArgparseDefinitionNames(node: SyntaxNode): SyntaxNode[] {\n // check if the node is a 'argparse' command\n if (!node || !isCommandWithName(node, 'argparse')) return [];\n // check if the node has a '--' token\n const endChar = node.children.find(node => isEndStdinCharacter(node));\n if (!endChar) return [];\n // get the children of the node that are not options and before the endChar (currently skips variables)\n const nodes = node.childrenForFieldName('argument')\n .filter(n => !isEscapeSequence(n) && isBefore(n, endChar))\n .filter(n => !isInvalidArgparseName(n));\n\n const { remaining } = findOptions(nodes, ArgparseOptions);\n return remaining;\n}\n\n/**\n * Checks if a node is an `argparse` definition variable\n * NOTE: if the node in question is a variable expansion, it will be skipped.\n * ```fish\n * argparse --max-args=2 --ignore-unknown --stop-nonopt h/help 'n/name=?' 'x/exclusive' -- $argv\n * ```\n * Would return true for the following SyntaxNodes passed in:\n * - `h/help`\n * - `n/name=?`\n * - `x/exclusive`\n * @param node The node to check, where it's parent isCommandWithName(parent, 'argparse'), and it's not a switch\n * @returns true if the node is an argparse definition variable (flags for the `argparse` command with be skipped)\n */\nexport function isArgparseVariableDefinitionName(node: SyntaxNode) {\n if (!node.parent || !isCommandWithName(node.parent, 'argparse')) return false;\n const children = findArgparseDefinitionNames(node.parent);\n return !!children.some(n => n.equals(node));\n}\n\nexport function convertNodeRangeWithPrecedingFlag(node: SyntaxNode) {\n const range = getRange(node);\n if (node.text.startsWith('_flag_')) {\n range.start = {\n line: range.start.line,\n character: range.start.character + 6,\n };\n }\n return range;\n}\n\nexport function isGlobalArgparseDefinition(document: LspDocument, symbol: FishSymbol) {\n if (!symbol.isArgparse() || !symbol.isFunction()) return false;\n let parent = symbol.parent;\n if (symbol.isFunction() && symbol.isGlobal()) {\n parent = symbol;\n }\n if (parent && parent?.isFunction()) {\n const functionName = parent.name;\n if (document.getAutoLoadName() !== functionName) {\n return false;\n }\n const filepath = document.getFilePath();\n // const workspaceDirectory = workspaces.find(ws => ws.contains(filepath) || ws.path === filepath)?.path || dirname(dirname(filepath));\n const workspaceDirectory = workspaceManager.findContainingWorkspace(document.uri)?.path || dirname(dirname(filepath));\n const completionFile = document.getAutoloadType() === 'conf.d' || document.getAutoloadType() === 'config'\n ? document.getFilePath()\n : path.join(\n workspaceDirectory,\n 'completions',\n document.getFilename(),\n );\n if (process.env.NODE_ENV !== 'test' && !SyncFileHelper.isFile(completionFile)) {\n return false;\n }\n return analyzer.getFlatCompletionSymbols(pathToUri(completionFile)).length > 0;\n }\n return false;\n}\n\n/**\n * This is really more of a utility to ensure that any document that would contain\n * any references to completions for an autoloaded file, is parsed by the analyzer.\n */\nexport function getGlobalArgparseLocations(document: LspDocument, symbol: FishSymbol) {\n if (isGlobalArgparseDefinition(document, symbol)) {\n const filepath = uriToPath(document.uri);\n const workspaceDirectory = workspaceManager.findContainingWorkspace(document.uri)?.path || dirname(dirname(filepath));\n logger.log(\n `Getting global argparse locations for symbol: ${symbol.name} in file: ${filepath}`,\n {\n filepath,\n workspaceDirectory,\n });\n const completionFile = document.getAutoloadType() === 'conf.d' || document.getAutoloadType() === 'config'\n ? document.getFilePath()\n : path.join(\n workspaceDirectory,\n 'completions',\n document.getFilename(),\n );\n if (process.env.NODE_ENV !== 'test' && !SyncFileHelper.isFile(completionFile)) {\n logger.debug({\n env: 'test',\n message: `Completion file does not exist: ${completionFile}`,\n });\n return [];\n }\n logger.debug({\n message: `Getting global argparse locations for symbol: ${symbol.name} in file: ${completionFile}`,\n });\n const completionLocations = analyzer\n .getFlatCompletionSymbols(pathToUri(completionFile))\n .filter(s => s.isNonEmpty())\n .filter(s => s.equalsArgparse(symbol) || s.equalsCommand(symbol))\n .map(s => s.toLocation());\n\n logger.log(`Found ${completionLocations.length} global argparse locations for symbol: ${symbol.name}`, 'HERE');\n\n // const containsOpt = analyzer.getNodes(pathToUri(completionFile)).filter(n => isCommandWithName(n, '__fish_contains_opt'));\n return completionLocations;\n }\n logger.warning(`no global argparse locations found for symbol: ${symbol.name}`, 'HERE');\n return [];\n}\n\nfunction getArgparseScopeModifier(document: LspDocument, _node: SyntaxNode): ScopeTag {\n const autoloadType = document.getAutoloadType();\n switch (autoloadType) {\n case 'conf.d':\n case 'config':\n case 'functions':\n return 'local';\n default:\n // return isTopLevelDefinition(node) ? 'global' : 'local';\n return 'local';\n }\n}\n\nexport function getArgparseDefinitionName(node: SyntaxNode): string {\n if (!node.parent || !isCommandWithName(node.parent, 'complete')) return '';\n if (node.text) {\n const text = `_flag_${node.text}`;\n return text.replace(/-/, '_');\n }\n return '';\n}\n\n/**\n * Checks if a syntax node is a completion argparse flag with a specific command name.\n *\n * On the input: `complete -c test -s h -l help -d 'show help info for the test command'`\n * ^---- node is here\n * A truthy result would be returned from the following function call:\n *\n * `isCompletionArgparseFlagWithCommandName(node, 'test', 'help')`\n * ___\n * @param node - The syntax node to check\n * @param commandName - The command name to match against\n * @param flagName - The flag name to match against\n * @param opts - Optional configuration options\n * @param opts.noCommandNameAllowed - When true, a completion without a `-c`/`--command` Option is allowed\n * @param opts.discardIfContainsOptions - A list of options that, if present, will cause the match to be discarded\n * @returns True if the node is a completion argparse flag with the specified command name\n */\nexport function isCompletionArgparseFlagWithCommandName(node: SyntaxNode, commandName: string, flagName: string, opts?: {\n noCommandNameAllowed?: boolean;\n discardIfContainsOptions?: Option[];\n}) {\n // make sure that the node we are checking is inside a completion definition\n if (!node?.parent || !isCommandWithName(node.parent, 'complete')) return false;\n\n // parent is the entire completion command\n const parent = node.parent;\n\n // check if any of the options to discard are seen\n if (opts?.discardIfContainsOptions) {\n for (const option of opts.discardIfContainsOptions) {\n if (parent.children.some(c => option.matches(c))) {\n return false;\n }\n }\n }\n\n // check if the command name is present in the completion\n let completeCmdName: boolean = !!parent.children.find(c =>\n c.previousSibling &&\n isMatchingOption(c.previousSibling, Option.create('-c', '--command')) &&\n c.text === commandName,\n );\n\n // if noCommandNameAllowed is true, and we don't have a command name yet\n // update the completeCmdName to be true if the `-c`/`--command` option is not present\n if (opts?.noCommandNameAllowed && !completeCmdName) {\n completeCmdName = !parent.children.some(c =>\n c.previousSibling &&\n isMatchingOption(c.previousSibling, Option.create('-c', '--command')),\n );\n }\n\n // Here we determine if which type of option we are looking for\n const option = flagName.length === 1\n ? Option.create('-s', '--short')\n : Option.create('-l', '--long');\n\n // check if the option name is present in the completion\n const completeFlagName: boolean = !!(\n node.previousSibling &&\n option.equals(node.previousSibling) &&\n node.text === flagName\n );\n\n // return true if both the command name and option name\n return completeCmdName && completeFlagName;\n}\n\nfunction createSelectionRange(node: SyntaxNode, flags: string[], flag: string, idx: number) {\n const range = getRange(node);\n const text = node.text;\n const shortenedFlag = flag.replace(/^_flag_/, '');\n if (flags.length === 2 && idx === 0) {\n if (isString(node)) {\n range.start = {\n line: range.start.line,\n character: range.start.character + 1,\n };\n range.end = {\n line: range.start.line,\n character: range.start.character - 1,\n };\n }\n return {\n start: range.start,\n end: {\n line: range.start.line,\n character: range.start.character + shortenedFlag.length,\n },\n };\n } else if (flags.length === 2 && idx === 1) {\n return {\n start: {\n line: range.start.line,\n character: range.start.character + text.indexOf('/') + 1,\n },\n end: {\n line: range.end.line,\n character: range.start.character + text.indexOf('/') + 1 + shortenedFlag.length,\n },\n };\n } else if (flags.length === 1) {\n if (isString(node)) {\n return {\n start: {\n line: range.start.line,\n character: range.start.character + 1,\n },\n end: {\n line: range.start.line,\n character: range.start.character + 1 + shortenedFlag.length,\n },\n };\n } else {\n return getRange(node);\n }\n }\n return range;\n}\n\n// split the `h/help` into `h` and `help`\nfunction splitSlash(str: string): string[] {\n const results = str.split('/')\n .map(s => s.trim().replace(/-/g, '_'));\n\n const maxResults = results.length < 2 ? results.length : 2;\n return results.slice(0, maxResults);\n}\n\n// get the flag variable names from the argparse commands\nfunction getNames(flags: string[]) {\n return flags.map(flag => {\n return `_flag_${flag}`;\n });\n}\n\n/**\n * Process an argparse command and return all of the flag definitions as a `FishSymbol[]`\n * @param document The LspDocument we are processing\n * @param node The node we are processing, should be isCommandWithName(node, 'argparse')\n * @param children The children symbols of the current FishSymbol's we are processing (likely empty)\n * @returns An array of FishSymbol's that represent the flags defined in the argparse command\n */\nexport function processArgparseCommand(document: LspDocument, node: SyntaxNode, children: FishSymbol[] = []) {\n const result: FishSymbol[] = [];\n // get the scope modifier\n const modifier = getArgparseScopeModifier(document, node);\n const scopeNode = findParentWithFallback(node, (n) => isFunctionDefinition(n));\n // array of nodes that are `argparse` flags\n const focuesedNodes = findArgparseDefinitionNames(node);\n // build the flags, and store them in the result array\n for (const n of focuesedNodes) {\n let flagNames = n.text;\n if (!flagNames) continue;\n // fixup the flag names for strings and concatenated flags\n if (isString(n)) flagNames = flagNames.slice(1, -1);\n if (flagNames.includes('=')) flagNames = flagNames.slice(0, flagNames.indexOf('='));\n // split the text into corresponding flags and convert them to `_flag_` format\n const seenFlags = splitSlash(flagNames);\n const names = getNames(seenFlags);\n // add all seenFlags to the `result: FishSymbol[]` array\n const flags = names.map((flagName, idx) => {\n const selectedRange = createSelectionRange(n, seenFlags, flagName, idx);\n return FishSymbol.fromObject({\n name: flagName,\n node: node,\n focusedNode: n,\n fishKind: 'ARGPARSE',\n document: document,\n uri: document.uri,\n detail: n.text,\n range: getRange(n),\n selectionRange: selectedRange,\n scope: DefinitionScope.create(scopeNode, modifier),\n children,\n }).addAliasedNames(...names);\n });\n result.push(...flags);\n }\n return result;\n}\n"
},
{
"path": "src/parsing/barrel.ts",
"content": "import * as SetParser from './set';\nimport * as ReadParser from './read';\nimport * as ForParser from './for';\nimport * as ArgparseParser from './argparse';\nimport * as AliasParser from './alias';\nimport * as ExportParser from './export';\nimport * as FunctionParser from './function';\nimport * as CompleteParser from './complete';\nimport * as OptionsParser from './options';\nimport * as SymbolParser from './symbol';\nimport * as EventParser from './emit';\nimport { SyntaxNode } from 'web-tree-sitter';\n\n/**\n * Internal SyntaxNode parsers for finding FishSymbol definitions\n * of any `FishKindType`. These are marked as internal because\n * ideally they will be exported through the `../utils/node-types.ts`\n * file, which is where we want to isolate importing SyntaxNode\n * checkers while using them throughout the code bases' files.\n */\n\n/** @internal */\nexport const Parsers = {\n set: SetParser,\n read: ReadParser,\n for: ForParser,\n argparse: ArgparseParser,\n function: FunctionParser,\n complete: CompleteParser,\n options: OptionsParser,\n symbol: SymbolParser,\n export: ExportParser,\n event: EventParser,\n};\n\n/** @internal */\nexport const VariableDefinitionKeywords = [\n 'set',\n 'read',\n 'argparse',\n 'for',\n 'function',\n 'export',\n];\n\n/**\n * @internal\n * Checks if a node is a variable definition name.\n * Examples of variable names include:\n * - `set -g -x foo '...'` -> foo\n * - `read -l bar baz` -> bar baz\n * - `argparse h/help -- $argv` -> h/help\n * - `for i in _ ` -> i\n * - `export foo=bar` -> foo\n */\nexport function isVariableDefinitionName(node: SyntaxNode) {\n return SetParser.isSetVariableDefinitionName(node) ||\n ReadParser.isReadVariableDefinitionName(node) ||\n ArgparseParser.isArgparseVariableDefinitionName(node) ||\n ForParser.isForVariableDefinitionName(node) ||\n FunctionParser.isFunctionVariableDefinitionName(node) ||\n ExportParser.isExportVariableDefinitionName(node);\n}\n\n/**\n * @internal\n * Checks if a node is a function definition name.\n * Examples of function names include:\n * - `function baz; end;` -> baz\n */\nexport function isFunctionDefinitionName(node: SyntaxNode) {\n return FunctionParser.isFunctionDefinitionName(node);\n}\n\n/**\n * @internal\n * Checks if a node is a alias definition name.\n * - `alias foo '__foo'` -> foo\n * - `alias bar='__bar'` -> bar\n */\nexport function isAliasDefinitionName(node: SyntaxNode) {\n return AliasParser.isAliasDefinitionName(node);\n}\n\n/**\n * @internal\n * Checks if a node is a function variable definition name.\n * - `emit event-name` -> event-name\n */\nexport function isEmittedEventDefinitionName(node: SyntaxNode) {\n return EventParser.isEmittedEventDefinitionName(node);\n}\n\n/**\n * @internal\n * Checks if a node is a export definition name.\n * - `export foo=__foo` -> foo\n * - `export bar='__bar'` -> bar\n */\nexport function isExportVariableDefinitionName(node: SyntaxNode) {\n return ExportParser.isExportVariableDefinitionName(node);\n}\n\n/**\n * @internal\n * Checks if a node is an `argparse` definition variable\n * NOTE: if the node in question is a variable expansion, it will be skipped.\n * ```fish\n * argparse --max-args=2 --ignore-unknown --stop-nonopt h/help 'n/name=?' 'x/exclusive' -- $argv\n * ```\n * Would return true for the following SyntaxNodes passed in:\n * - `h/help`\n * - `n/name=?`\n * - `x/exclusive`\n * @param node The node to check, where it's parent isCommandWithName(parent, 'argparse'), and it's not a switch\n * @returns true if the node is an argparse definition variable (flags for the `argparse` command with be skipped)\n */\nexport function isArgparseVariableDefinitionName(node: SyntaxNode) {\n return ArgparseParser.isArgparseVariableDefinitionName(node);\n}\n\n/**\n * @internal\n * Checks if a node is a definition name.\n * Definition names are variable names (read/set/argparse/function flags), function names (alias/function),\n */\nexport function isDefinitionName(node: SyntaxNode) {\n return isVariableDefinitionName(node) || isFunctionDefinitionName(node) || isAliasDefinitionName(node);\n}\n\n/**\n * @internal\n */\nexport const NodeTypes = {\n isVariableDefinitionName: isVariableDefinitionName,\n isFunctionDefinitionName: isFunctionDefinitionName,\n isAliasDefinitionName: isAliasDefinitionName,\n isDefinitionName: isDefinitionName,\n isSetVariableDefinitionName: SetParser.isSetVariableDefinitionName,\n isReadVariableDefinitionName: ReadParser.isReadVariableDefinitionName,\n isForVariableDefinitionName: ForParser.isForVariableDefinitionName,\n isExportVariableDefinitionName: ExportParser.isExportVariableDefinitionName,\n isArgparseVariableDefinitionName: ArgparseParser.isArgparseVariableDefinitionName,\n isFunctionVariableDefinitionName: FunctionParser.isFunctionVariableDefinitionName,\n isMatchingOption: OptionsParser.isMatchingOption,\n};\n\n/**\n * @internal\n */\nexport const ParsingDefinitionNames = {\n isSetVariableDefinitionName: SetParser.isSetVariableDefinitionName,\n isReadVariableDefinitionName: ReadParser.isReadVariableDefinitionName,\n isForVariableDefinitionName: ForParser.isForVariableDefinitionName,\n isArgparseVariableDefinitionName: ArgparseParser.isArgparseVariableDefinitionName,\n isFunctionVariableDefinitionName: FunctionParser.isFunctionVariableDefinitionName,\n isFunctionDefinitionName: FunctionParser.isFunctionDefinitionName,\n isAliasDefinitionName: AliasParser.isAliasDefinitionName,\n isExportDefinitionName: ExportParser.isExportVariableDefinitionName,\n} as const;\n\ntype DefinitionNodeNameTypes = 'isDefinitionName' | 'isVariableDefinitionName' | 'isFunctionDefinitionName' | 'isAliasDefinitionName';\ntype DefinitionNodeChecker = (n: SyntaxNode) => boolean;\n/** @internal */\nexport const DefinitionNodeNames: Record = {\n isDefinitionName: isDefinitionName,\n isVariableDefinitionName: isVariableDefinitionName,\n isFunctionDefinitionName: isFunctionDefinitionName,\n isAliasDefinitionName: isAliasDefinitionName,\n};\n\n/** @internal */\nexport * from './options';\n\n/** @internal */\nexport const parsers = Object.keys(Parsers).map(key => Parsers[key as keyof typeof Parsers]);\n\n/** @internal */\nexport {\n SetParser,\n ReadParser,\n ForParser,\n ArgparseParser,\n AliasParser,\n FunctionParser,\n ExportParser,\n CompleteParser,\n OptionsParser,\n SymbolParser,\n};\n"
},
{
"path": "src/parsing/bind.ts",
"content": "import { SyntaxNode } from 'web-tree-sitter';\nimport { findOptions, Option } from './options';\nimport { findParentCommand, isCommandWithName, isFunctionDefinitionName } from '../utils/node-types';\n\nexport const BindOptions = [\n Option.create('-f', '--function-names'),\n Option.create('-K', '--key-names'),\n Option.create('-L', '--list-modes'),\n Option.create('-M', '--mode').withValue(),\n Option.create('-m', '--new-mode').withValue(),\n Option.create('-e', '--erase'),\n Option.create('-a', '--all'),\n Option.long('--preset').withAliases('--user'),\n Option.create('-s', '--silent'),\n Option.create('-h', '--help'),\n];\n\n/**\n * Checks if a node is a bind command. `bind ...`\n */\nexport function isBindCommand(node: SyntaxNode) {\n return isCommandWithName(node, 'bind');\n}\n\n/**\n * Checks if a node is a bind command's key sequence.\n * `bind -M insert ctrl-r ...` -> ctrl-r\n */\nexport function isBindKeySequence(node: SyntaxNode) {\n const parent = findParentCommand(node);\n if (!parent || !isBindCommand(parent)) {\n return false;\n }\n const children = parent.namedChildren.slice(1);\n const optionResults = findOptions(children, BindOptions);\n const { remaining } = optionResults;\n return remaining.at(0)?.equals(node);\n}\n\n/**\n * Checks if a node is a bind command's function call, which\n * is any argument after the key sequence && bind options on\n * a `bind -M default ctrl-r cmd1 cmd2 cmd3` -> cmd1, cmd2, cmd3\n */\nexport function isBindFunctionCall(node: SyntaxNode) {\n const parent = findParentCommand(node);\n if (!parent || !isBindCommand(parent)) {\n return false;\n }\n const children = parent.namedChildren.slice(1);\n const optionResults = findOptions(children, BindOptions);\n const { remaining } = optionResults;\n const functionCalls = remaining.slice(1);\n return functionCalls.some(child => isFunctionDefinitionName(child) && child.equals(node));\n}\n"
},
{
"path": "src/parsing/comments.ts",
"content": "import { SyntaxNode } from 'web-tree-sitter';\nimport { isComment } from '../utils/node-types';\nimport { analyzer } from '../analyze';\nimport { getChildNodes } from '../utils/tree-sitter';\nimport { LspDocument } from '../document';\n\nexport const INDENT_COMMENT_REGEX = /^#\\s*@fish_indent(?::\\s*(off|on)?)?$/;\n\nexport function isIndentComment(node: SyntaxNode): boolean {\n if (!isComment(node)) return false;\n return INDENT_COMMENT_REGEX.test(node.text.trim());\n}\n\nexport interface IndentComment {\n node: SyntaxNode;\n indent: 'on' | 'off';\n line: number;\n}\n\nexport function parseIndentComment(node: SyntaxNode): IndentComment | null {\n if (!isIndentComment(node)) return null;\n const match = node.text.trim().match(INDENT_COMMENT_REGEX);\n if (!match) return null;\n return {\n node,\n indent: match[1] === 'off' ? 'off' : 'on',\n line: node.startPosition.row,\n };\n}\n\nexport function processIndentComments(root: SyntaxNode): IndentComment[] {\n const comments: IndentComment[] = [];\n for (const node of getChildNodes(root)) {\n if (isIndentComment(node)) {\n const indentComment = parseIndentComment(node);\n if (indentComment) {\n comments.push(indentComment);\n }\n }\n }\n return comments;\n}\n\nexport interface FormatRange {\n start: number; // line number (0-based)\n end: number; // line number (0-based)\n}\n\nexport interface FormatRanges {\n formatRanges: FormatRange[];\n fullDocumentFormatting: boolean;\n}\n\nexport function getEnabledIndentRanges(doc: LspDocument, rootNode?: SyntaxNode): FormatRanges {\n let root = rootNode;\n if (!root) {\n root = analyzer.getRootNode(doc.uri);\n if (!root) return { formatRanges: [], fullDocumentFormatting: true };\n }\n\n const comments = processIndentComments(root);\n if (comments.length === 0) {\n // No indent comments found - format entire document\n return {\n formatRanges: [{ start: 0, end: root.endPosition.row }],\n fullDocumentFormatting: true,\n };\n }\n\n const ranges: FormatRange[] = [];\n let currentStart = 0; // Start formatting from beginning\n let isCurrentlyEnabled = true; // Formatting is enabled by default\n\n for (const comment of comments) {\n if (comment.indent === 'off' && isCurrentlyEnabled) {\n // End current formatting range\n if (comment.line > currentStart) {\n ranges.push({ start: currentStart, end: comment.line - 1 });\n }\n isCurrentlyEnabled = false;\n } else if (comment.indent === 'on' && !isCurrentlyEnabled) {\n // Start new formatting range\n currentStart = comment.line + 1;\n isCurrentlyEnabled = true;\n }\n }\n\n // If we end with formatting enabled, add final range\n if (isCurrentlyEnabled && currentStart <= root.endPosition.row) {\n ranges.push({ start: currentStart, end: root.endPosition.row });\n }\n\n return {\n formatRanges: ranges,\n fullDocumentFormatting: false,\n };\n}\n"
},
{
"path": "src/parsing/complete.ts",
"content": "import { SyntaxNode } from 'web-tree-sitter';\nimport { isCommand, isCommandWithName, isOption, isString } from '../utils/node-types';\nimport { FishString } from './string';\nimport { Flag, isMatchingOption, Option } from './options';\nimport { LspDocument } from '../document';\nimport { getChildNodes, getRange, pointToPosition } from '../utils/tree-sitter';\nimport { FishSymbol } from './symbol';\nimport { Location, Range } from 'vscode-languageserver';\nimport { logger } from '../logger';\nimport { extractCommands } from './nested-strings';\n\nexport const CompleteOptions = [\n Option.create('-c', '--command').withValue(),\n Option.create('-p', '--path'),\n Option.create('-e', '--erase'),\n Option.create('-s', '--short-option').withValue(),\n Option.create('-l', '--long-option').withValue(),\n Option.create('-o', '--old-option').withValue(),\n Option.create('-a', '--arguments').withValue(),\n Option.create('-k', '--keep-order'),\n Option.create('-f', '--no-files'),\n Option.create('-F', '--force-files'),\n Option.create('-r', '--require-parameter'),\n Option.create('-x', '--exclusive'),\n Option.create('-d', '--description').withValue(),\n Option.create('-w', '--wraps').withValue(),\n Option.create('-n', '--condition').withValue(),\n Option.create('-C', '--do-complete').withValue(),\n Option.long('--escape').withValue(),\n Option.create('-h', '--help'),\n];\n\nexport function isCompletionCommandDefinition(node: SyntaxNode) {\n return isCommandWithName(node, 'complete');\n}\n\nexport function isMatchingCompletionFlagNodeWithFishSymbol(symbol: FishSymbol, node: SyntaxNode) {\n if (!node?.parent || isCommand(node) || isOption(node)) return false;\n\n const prevNode = node.previousNamedSibling;\n if (!prevNode) return false;\n\n if (symbol.isFunction()) {\n if (isMatchingOption(\n prevNode,\n Option.create('-c', '--command'),\n Option.create('-w', '--wraps'),\n )) {\n return symbol.name === node.text && !symbol.equalsNode(node);\n }\n\n if (isMatchingOption(\n prevNode,\n Option.create('-n', '--condition'),\n Option.create('-a', '--arguments'),\n )) {\n return isString(node)\n ? extractCommands(node).some(cmd => cmd === symbol.name)\n : node.text === symbol.name;\n }\n }\n\n if (symbol.isArgparse()) {\n if (isCompletionSymbol(node)) {\n const completionSymbol = getCompletionSymbol(node);\n return completionSymbol.equalsArgparse(symbol);\n }\n }\n\n if (symbol.isVariable()) {\n return node.text === symbol.name;\n }\n return false;\n}\n\nexport function isCompletionDefinitionWithName(node: SyntaxNode, name: string, doc: LspDocument) {\n if (node.parent && isCompletionCommandDefinition(node.parent)) {\n const symbol = getCompletionSymbol(node.parent, doc);\n return symbol?.commandName === name && isCompletionSymbol(node);\n }\n return false;\n}\n\nexport function isCompletionSymbolShort(node: SyntaxNode) {\n if (node.parent && isCompletionCommandDefinition(node.parent)) {\n return node.previousSibling && isMatchingOption(node.previousSibling, Option.create('-s', '--short-option'));\n }\n return false;\n}\n\nexport function isCompletionSymbolLong(node: SyntaxNode) {\n if (node.parent && isCompletionCommandDefinition(node.parent)) {\n return node.previousSibling && isMatchingOption(node.previousSibling, Option.create('-l', '--long-option'));\n }\n return false;\n}\n\nexport function isCompletionSymbolOld(node: SyntaxNode) {\n if (node.parent && isCompletionCommandDefinition(node.parent)) {\n return node.previousSibling && isMatchingOption(node.previousSibling, Option.create('-o', '--old-option'));\n }\n return false;\n}\n\nexport function isCompletionSymbol(node: SyntaxNode) {\n return isCompletionSymbolShort(node)\n || isCompletionSymbolLong(node)\n || isCompletionSymbolOld(node);\n}\n\ntype OptionType = '' | 'short' | 'long' | 'old';\nexport class CompletionSymbol {\n constructor(\n public optionType: OptionType = '',\n public commandName: string = '',\n public node: SyntaxNode | null = null,\n public description: string = '',\n public condition: string = '',\n public requireParameter: boolean = false,\n public argumentNames: string = '',\n public exclusive: boolean = false,\n public document?: LspDocument,\n ) {}\n\n /**\n * Initialize the VerboseCompletionSymbol with empty values.\n */\n static createEmpty() {\n return new CompletionSymbol();\n }\n\n /**\n * util for building a VerboseCompletionSymbol\n */\n static create({\n optionType = '',\n commandName = '',\n node = null,\n description = '',\n condition = '',\n requireParameter = false,\n argumentNames = '',\n exclusive = false,\n }: {\n optionType?: OptionType;\n commandName?: string;\n node?: SyntaxNode | null;\n description?: string;\n condition?: string;\n requireParameter?: boolean;\n argumentNames?: string;\n exclusive?: boolean;\n }) {\n return new this(optionType, commandName, node, description, condition, requireParameter, argumentNames, exclusive);\n }\n\n /**\n * If the node is not found, we don't have a valid VerboseCompletionSymbol.\n */\n isEmpty() {\n return this.node === null;\n }\n\n /**\n * Type Guard that our node & its parent are defined,\n * therefore we have found a valid VerboseCompletionSymbol.\n */\n isNonEmpty(): this is CompletionSymbol & { node: SyntaxNode; parent: SyntaxNode; } {\n return this.node !== null && this.parent !== null;\n }\n\n /**\n * Getter (w/ type guarding) to retrieve the CompletionSymbol.node.parent\n * Removes the pattern of null checking a CompletionSymbol.node.parent\n */\n get parent() {\n if (this.node) {\n return this.node.parent;\n }\n return null;\n }\n\n /**\n * Getter (w/ type guarding) to retrieve the CompletionSymbol.node.text\n * Removes the pattern of null checking a CompletionSymbol.node\n */\n get text(): string {\n if (this.isNonEmpty()) {\n return this.node.text;\n }\n return '';\n }\n\n /**\n * Check if the option is a short option: `-s ` or `--short-option `.\n */\n isShort() {\n return this.optionType === 'short';\n }\n\n /**\n * Check if the option is a long option: `-l ` or `--long-option `.\n */\n isLong() {\n return this.optionType === 'long';\n }\n\n /**\n * Check if the option is an old option: `-o ` or `--old-option `.\n */\n isOld() {\n return this.optionType === 'old';\n }\n\n /**\n * Check if one option is a pair of another option.\n * ```fish\n * complete -c foo -s h -l help # 'h' <--> 'help' are pairs\n * ```\n */\n isCorrespondingOption(other: CompletionSymbol) {\n if (!this.isNonEmpty() || !other.isNonEmpty()) {\n return false;\n }\n return this.parent.equals(other.parent)\n && this.commandName === other.commandName\n && this.optionType !== other.optionType;\n }\n\n /**\n * Return the `-f`/`--flag`/`-flag` string\n */\n toFlag() {\n if (!this.isNonEmpty()) return '';\n switch (this.optionType) {\n case 'short':\n case 'old':\n return `-${this.node.text}`;\n case 'long':\n return `--${this.node.text}`;\n default:\n return '';\n }\n }\n\n /**\n * return the commandName and the flag as a string\n */\n toUsage() {\n if (!this.isNonEmpty()) {\n return '';\n }\n return `${this.commandName} ${this.toFlag()}`;\n }\n\n /**\n * return the usage, with the description in a trailing comment\n */\n toUsageVerbose() {\n if (!this.isNonEmpty()) {\n return '';\n }\n return `${this.commandName} ${this.toFlag()} # ${this.description}`;\n }\n\n /**\n * check if the symbol inside a globally defined `argparse o/opt -- $argv` matches\n * this VerboseCompletionSymbol\n */\n equalsArgparse(symbol: FishSymbol) {\n if (symbol.fishKind !== 'ARGPARSE' || !symbol.parent) {\n return false;\n }\n const commandName = symbol.parent.name;\n const symbolName = symbol.argparseFlagName;\n return this.commandName === commandName\n && this.node?.text === symbolName;\n }\n\n equalsCommand(symbol: FishSymbol) {\n if (!symbol.isFunction()) {\n return false;\n }\n const commandName = symbol.name;\n return this.hasCommandName(commandName);\n }\n\n /**\n * Check if our CompletionSymbol.node === the node passed in\n */\n equalsNode(n: SyntaxNode) {\n return this.node?.equals(n);\n }\n\n /**\n * check if our CompletionSymbol.commandName === the commandName passed in\n */\n hasCommandName(name: string) {\n return this.commandName === name;\n }\n\n /**\n * A test utility for easily getting a completion flag\n */\n isMatchingRawOption(...opts: Flag[]) {\n const flag = this.toFlag();\n for (const opt of opts) {\n if (flag === opt) {\n return true;\n }\n }\n return false;\n }\n\n /**\n * utility to get the range of the node\n */\n getRange(): Range {\n if (this.isNonEmpty()) {\n return getRange(this.node);\n }\n return null as never;\n }\n\n /**\n * Create a Location from the current CompletionSymbol\n */\n toLocation(): Location {\n return Location.create(this.document?.uri || '', this.getRange());\n }\n\n toPosition(): { line: number; character: number; } | null {\n if (this.isNonEmpty()) {\n return pointToPosition(this.node.startPosition);\n }\n return null as never;\n }\n\n /**\n * Alias for the `this.text` property. Helps with readability, when comparing Argparse FishSymbols, to the string representation of the option.\n *\n * ```fish\n * complete -c foo -s h -l help\n * # ^ ^^^^ are both our `text` properties, we can build a string representation of the argparse option `h/help`\n * ```\n *\n * ```fish\n * function foo\n * argparse h/help -- $argv\n * end\n * ```\n * Returns the string representation of the option, e.g. `-h`, `--help`, or `-h/--help`.\n */\n toArgparseOpt(): string {\n if (!this.isNonEmpty()) {\n return '';\n }\n return this.text;\n }\n\n /**\n * Example: { name: `help-msg` } -> `_flag_help_msg`\n * Returns the variable name that argparse would create for this completion.\n */\n toArgparseVariableName(): string {\n const prefix = '_flag_';\n const fixString = (str: string) => str.replace(/-/g, '_');\n if (!this.isNonEmpty()) {\n return '';\n }\n return prefix + fixString(this.text);\n }\n\n static is(obj: unknown): obj is CompletionSymbol {\n if (!obj || typeof obj !== 'object') {\n return false;\n }\n return obj instanceof CompletionSymbol\n && typeof obj.optionType === 'string'\n && typeof obj.commandName === 'string'\n && typeof obj.description === 'string'\n && typeof obj.condition === 'string'\n && typeof obj.requireParameter === 'boolean'\n && typeof obj.argumentNames === 'string';\n }\n}\n\nexport function isCompletionSymbolVerbose(node: SyntaxNode, doc?: LspDocument): boolean {\n if (isCompletionSymbol(node) || !node.parent) {\n return true;\n }\n if (node.parent && isCompletionCommandDefinition(node.parent)) {\n const symbol = getCompletionSymbol(node, doc);\n return symbol?.isNonEmpty() || false;\n }\n return false;\n}\n\n/**\n * Create a VerboseCompletionSymbol from a SyntaxNode, for any SyntaxNode passed in.\n * Calling this function will need to check if `result.isEmpty()` or `result.isNonEmpty()`\n * @param node any syntax node, preferably one that is a child of a `complete` node (not required though)\n * @returns {CompletionSymbol} `result.isEmpty()` when not found, `result.isNonEmpty()` when `isCompletionSymbolVerbose(node)` is found\n */\nexport function getCompletionSymbol(node: SyntaxNode, doc?: LspDocument): CompletionSymbol {\n const result = CompletionSymbol.createEmpty();\n if (!isCompletionSymbol(node) || !node.parent) {\n return result;\n }\n switch (true) {\n case isCompletionSymbolShort(node):\n result.optionType = 'short';\n break;\n case isCompletionSymbolLong(node):\n result.optionType = 'long';\n break;\n case isCompletionSymbolOld(node):\n result.optionType = 'old';\n break;\n default:\n break;\n }\n result.node = node;\n const parent = node.parent;\n const children = parent.childrenForFieldName('argument');\n result.document = doc;\n children.forEach((child, idx) => {\n if (idx === 0) return;\n if (isMatchingOption(child, Option.create('-r', '--require-parameter'))) {\n result.requireParameter = true;\n }\n if (isMatchingOption(child, Option.create('-x', '--exclusive'))) {\n result.exclusive = true;\n }\n const prev = child.previousSibling;\n if (!prev) return;\n if (isMatchingOption(prev, Option.create('-c', '--command'))) {\n result.commandName = child.text;\n }\n if (isMatchingOption(prev, Option.create('-d', '--description'))) {\n result.description = FishString.fromNode(child);\n }\n if (isMatchingOption(prev, Option.create('-n', '--condition'))) {\n result.condition = child.text;\n }\n if (isMatchingOption(prev, Option.create('-a', '--arguments'))) {\n result.argumentNames = child.text;\n }\n });\n return result;\n}\n\nexport function groupCompletionSymbolsTogether(\n ...symbols: CompletionSymbol[]\n): CompletionSymbol[][] {\n const storedSymbols: Set = new Set();\n const groupedSymbols: CompletionSymbol[][] = [];\n symbols.forEach((symbol) => {\n if (storedSymbols.has(symbol.text)) {\n return;\n }\n const newGroup: CompletionSymbol[] = [symbol];\n const matches = symbols.filter((s) => s.isCorrespondingOption(symbol));\n matches.forEach((s) => {\n storedSymbols.add(s.text);\n newGroup.push(s);\n });\n groupedSymbols.push(newGroup);\n });\n return groupedSymbols;\n}\n\nexport function getGroupedCompletionSymbolsAsArgparse(groupedCompletionSymbols: CompletionSymbol[][], argparseSymbols: FishSymbol[]): CompletionSymbol[][] {\n const missingArgparseValues: CompletionSymbol[][] = [];\n for (const symbolGroup of groupedCompletionSymbols) {\n if (argparseSymbols.some(argparseSymbol => symbolGroup.find(s => s.equalsArgparse(argparseSymbol)))) {\n logger.info({\n message: 'Skipping symbol group that already has an argparse value',\n symbolGroup: symbolGroup.map(s => s.toFlag()),\n focusedSymbols: argparseSymbols.find(fs => symbolGroup.find(s => s.equalsArgparse(fs)))?.name,\n });\n continue;\n }\n missingArgparseValues.push(symbolGroup);\n }\n return missingArgparseValues;\n}\n\nexport function processCompletion(document: LspDocument, node: SyntaxNode) {\n const result: CompletionSymbol[] = [];\n for (const child of getChildNodes(node)) {\n if (isCompletionCommandDefinition(node)) {\n const newSymbol = getCompletionSymbol(child, document);\n if (newSymbol) result.push(newSymbol);\n }\n }\n return result;\n}\n"
},
{
"path": "src/parsing/emit.ts",
"content": "import { SyntaxNode } from 'web-tree-sitter';\nimport { isCommandWithName, isFunctionDefinition } from '../utils/node-types';\nimport { FishSymbol } from './symbol';\nimport { DefinitionScope, ScopeTag } from '../utils/definition-scope';\nimport { LspDocument } from '../document';\nimport { getRange } from '../utils/tree-sitter';\nimport { md } from '../utils/markdown-builder';\nimport { unindentNestedSyntaxNode } from './symbol-detail';\nimport { findFunctionOptionNamedArguments } from './function';\n\n/**\n * Check if a SyntaxNode is an emitted/fired event definition name\n * ```fish\n * emit my_event_name\n * # ^^^^^^^^^^^^^^ This is the emitted event definition name\n * ```\n * @param node - The SyntaxNode to check\n * @return {boolean} - True if the node is an emitted event definition name, false otherwise\n */\nexport function isEmittedEventDefinitionName(node: SyntaxNode): boolean {\n if (!node.parent || !node.isNamed) return false;\n\n if (!isCommandWithName(node.parent, 'emit')) {\n return false;\n }\n\n return !!(node.parent.namedChild(1) && node.parent.namedChild(1)?.equals(node));\n}\n\n/**\n * Finds the emitted event definition name from a command node.\n * ```fish\n * emit my_event_name\n * # ^^^^----------------- searches here\n * # ^^^^^^^^^^^^^--- returns this node\n * ```\n */\nfunction findEmittedEventDefinitionName(node: SyntaxNode): SyntaxNode | undefined {\n if (!isCommandWithName(node, 'emit')) return undefined;\n if (node.namedChild(1)) return node.namedChild(1) || undefined;\n return undefined;\n}\n\n/**\n * Checks if a SyntaxNode is a generic event handler name, in a function definition\n *\n * ```fish\n * function my_function --on-event my_event_name\n * # ^^^^^^^^^^^^^^^^^^^^^^ This is the event handler definition name\n * end\n * ````\n *\n * @param node - The SyntaxNode to check\n * @return {boolean} - True if the node is a generic event handler definition name, false otherwise\n */\nexport function isGenericFunctionEventHandlerDefinitionName(node: SyntaxNode): boolean {\n if (!node.parent || !node.isNamed) return false;\n\n // Check if the parent is a function definition with an event handler option\n if (!isFunctionDefinition(node.parent)) return false;\n const { eventNodes } = findFunctionOptionNamedArguments(node.parent);\n return eventNodes.some(eventNode => eventNode.equals(node));\n}\n\n/**\n * Processes an emit event command node and returns a FishSymbol representing the emitted event.\n *\n * Note: The processFunctionDefinition() function also handles building Event Symbols, but\n * specifically creates them for `function ... --on-event NAME` (`fishKind === 'FUNCTION_EVENT'`),\n * where as, this function creates symbols for `emit NAME` commands (`fishKind === 'EVENT'`).\n *\n * @param document - The LspDocument containing the node\n * @param node - The SyntaxNode representing the emit command\n * @param children - Optional array of child FishSymbols\n *\n * @returns {FishSymbol[]} - An array containing a FishSymbol for the emitted event\n */\nexport function processEmitEventCommandName(document: LspDocument, node: SyntaxNode, children: FishSymbol[] = []): FishSymbol[] {\n const emittedEventNode = findEmittedEventDefinitionName(node);\n if (!emittedEventNode) return [];\n\n const eventName = emittedEventNode.text;\n\n const parentCommand = node;\n\n const scopeTag: ScopeTag = document.isAutoloaded()\n ? 'global'\n : 'local';\n\n return [\n new FishSymbol({\n name: eventName,\n fishKind: 'EVENT',\n node: parentCommand,\n children,\n document: document,\n scope: DefinitionScope.create(node, scopeTag),\n focusedNode: emittedEventNode,\n range: getRange(parentCommand),\n detail: [\n `(${md.bold('event')}) ${md.inlineCode(eventName)}`,\n md.separator(),\n md.codeBlock('fish', [\n '### emit/fire a generic event',\n unindentNestedSyntaxNode(parentCommand),\n ].join('\\n')),\n md.separator(),\n md.boldItalic('SEE ALSO:'),\n ' • Emit Events: https://fishshell.com/docs/current/cmds/emit.html',\n ' • Event Handling: https://fishshell.com/docs/current/language.html#event',\n ].join(md.newline()),\n }),\n ];\n}\n"
},
{
"path": "src/parsing/equality-utils.ts",
"content": "import { Location, Position, Range } from 'vscode-languageserver';\nimport { SyntaxNode } from 'web-tree-sitter';\nimport { FishSymbol } from './symbol';\nimport { isFunctionDefinition } from '../utils/node-types';\nimport { containsNode as nodeContainsNode, getRange } from '../utils/tree-sitter';\n\n// === TYPES ===\n\ntype SymbolPair = {\n a: FishSymbol;\n b: FishSymbol;\n};\n\ntype EqualityCheck = (pair: SymbolPair) => boolean;\ntype ScopeCheck = (pair: SymbolPair) => boolean;\n\n// === RANGE & POSITION UTILITIES ===\n\n// Check if two ranges are identical\nexport const rangesEqual = (range1: Range, range2: Range): boolean => {\n return range1.start.line === range2.start.line &&\n range1.start.character === range2.start.character &&\n range1.end.line === range2.end.line &&\n range1.end.character === range2.end.character;\n};\n\n// Check if a range contains a position\nexport const rangeContainsPosition = (range: Range, position: Position): boolean => {\n const { line, character } = position;\n const { start, end } = range;\n\n if (line < start.line || line > end.line) return false;\n if (line === start.line && character < start.character) return false;\n if (line === end.line && character > end.character) return false;\n\n return true;\n};\n\n// Check if a range contains a syntax node (by comparing line numbers only)\nexport const rangeContainsSyntaxNode = (range: Range, node: SyntaxNode): boolean => {\n return range.start.line <= node.startPosition.row &&\n range.end.line >= node.endPosition.row;\n};\n\n// === SYMBOL EQUALITY CHECKING ===\n\n// Check if two symbols have matching names (including aliases)\nconst hasEqualNames: EqualityCheck = ({ a, b }) => {\n if (a.name === b.name) return true;\n return a.aliasedNames.includes(b.name) || b.aliasedNames.includes(a.name);\n};\n\n// Check if two symbols have identical ranges\nconst hasEqualRanges: EqualityCheck = ({ a, b }) => {\n return rangesEqual(a.range, b.range) && rangesEqual(a.selectionRange, b.selectionRange);\n};\n\n// Check if two symbols have matching basic properties\nconst hasEqualBasicProperties: EqualityCheck = ({ a, b }) => {\n return a.kind === b.kind &&\n a.uri === b.uri &&\n a.fishKind === b.fishKind;\n};\n\n// Main equality checker\nexport const equalSymbols = (symbolA: FishSymbol, symbolB: FishSymbol): boolean => {\n const pair: SymbolPair = { a: symbolA, b: symbolB };\n\n return hasEqualNames(pair) &&\n hasEqualBasicProperties(pair) &&\n hasEqualRanges(pair);\n};\n\n// === LOCATION EQUALITY ===\n\n// Check if a symbol's location equals a given Location\nexport const symbolEqualsLocation = (symbol: FishSymbol, location: Location): boolean => {\n return symbol.uri === location.uri &&\n rangesEqual(symbol.selectionRange, location.range);\n};\n\n// === DEFINITION EQUALITY ===\n\n// Check if two symbols represent the same definition\nexport const equalSymbolDefinitions = (symbolA: FishSymbol, symbolB: FishSymbol): boolean => {\n return symbolA.name === symbolB.name &&\n symbolA.kind === symbolB.kind &&\n symbolA.uri === symbolB.uri &&\n symbolContainsScope(symbolA, symbolB);\n};\n\n// === NODE EQUALITY ===\n\n// Check if symbol equals a syntax node (with optional strict mode)\nexport const symbolEqualsNode = (symbol: FishSymbol, node: SyntaxNode, strict = false): boolean => {\n if (strict) return symbol.focusedNode.equals(node);\n return symbol.node.equals(node) || symbol.focusedNode.equals(node);\n};\n\n// === CONTAINMENT CHECKING ===\n\n// Check if symbol's scope contains a syntax node\nexport const symbolScopeContainsNode = (symbol: FishSymbol, node: SyntaxNode): boolean => {\n return symbol.scope.containsPosition(getRange(node).start);\n};\n\n// Check if symbol contains a syntax node (by range)\nexport const symbolContainsNode = (symbol: FishSymbol, node: SyntaxNode): boolean => {\n return rangeContainsSyntaxNode(symbol.range, node);\n};\n\n// Check if symbol contains a position\nexport const symbolContainsPosition = (symbol: FishSymbol, position: Position): boolean => {\n const { line, character } = position;\n const { start, end } = symbol.selectionRange;\n\n return start.line === line &&\n start.character <= character &&\n end.character >= character;\n};\n\n// === SCOPE CHECKING ===\n\n// Check if two symbols have identical scope nodes\nconst haveSameScopeNode: ScopeCheck = ({ a, b }) => {\n if (a.scopeTag === 'inherit' || b.scopeTag === 'inherit') {\n return a.scopeContainsNode(b.node) || b.scopeContainsNode(a.node);\n }\n if (a.isLocal() && b.isLocal() && a.kind === b.kind && a.isVariable() && b.isVariable()) {\n return a.scopeContainsNode(b.node) || b.scopeContainsNode(a.node);\n }\n return a.scope.scopeNode.equals(b.scope.scopeNode);\n};\n\n// Check if two symbols have compatible scope tags\nconst haveCompatibleScopeTags: ScopeCheck = ({ a, b }) => {\n const scopeTags = [a.scope.scopeTag, b.scope.scopeTag];\n\n // Special cases for scope compatibility\n if (scopeTags.includes('inherit')) return true;\n if (a.isLocal() && b.isLocal() && a.kind === b.kind && a.isVariable() && b.isVariable()) return true;\n if (a.isGlobal() && b.isGlobal()) return true;\n if (a.isLocal() && b.isLocal()) return true;\n\n return a.scope.scopeTag === b.scope.scopeTag;\n};\n\n// Check if scopes are equal\nconst haveEqualScopes: ScopeCheck = ({ a, b }) => {\n if (!haveSameScopeNode({ a, b }) || a.kind !== b.kind) return false;\n return haveCompatibleScopeTags({ a, b });\n};\n\n// Check scope containment for variables specifically\nconst checkVariableScopeContainment: ScopeCheck = ({ a, b }) => {\n if (!a.isVariable() || !b.isVariable()) return false;\n\n // Both global variables\n if (a.isGlobal() && b.isGlobal()) return true;\n\n // if one of the tags is global and the other is local, they cannot contain each other\n if (a.isGlobal() && b.isLocal() || a.isLocal() && b.isGlobal()) {\n return false;\n }\n const isSameScope = haveSameScopeNode({ a, b });\n const scopeContains = nodeContainsNode(a.scope.scopeNode, b.scope.scopeNode);\n\n // Special handling for function definitions\n if (isFunctionDefinition(a.scopeNode) && isFunctionDefinition(b.scopeNode)) {\n return isSameScope;\n }\n\n return isSameScope || scopeContains;\n};\n\n// Check scope containment for general case (used by symbolContainsScope)\nconst checkGeneralScopeContainment: ScopeCheck = ({ a, b }) => {\n if (!haveSameScopeNode({ a, b }) || a.kind !== b.kind) return false;\n\n const scopeTags = [a.scope.scopeTag, b.scope.scopeTag];\n\n // Handle inherit scope or local variables of same kind\n if (scopeTags.includes('inherit') ||\n a.isLocal() && b.isLocal() && a.kind === b.kind && a.isVariable() && b.isVariable()) {\n if (isFunctionDefinition(a.scope.scopeNode) && isFunctionDefinition(b.scope.scopeNode)) {\n return true;\n }\n\n return haveSameScopeNode({ a, b }) || nodeContainsNode(a.scope.scopeNode, b.scope.scopeNode);\n }\n\n // Handle global/local scope combinations\n if (a.isGlobal() && b.isGlobal()) return true;\n if (a.isLocal() && b.isLocal()) return true;\n\n return a.scope.scopeTag === b.scope.scopeTag;\n};\n\n// Main scope containment checker\nexport const symbolContainsScope = (symbolA: FishSymbol, symbolB: FishSymbol): boolean => {\n const pair: SymbolPair = { a: symbolA, b: symbolB };\n\n // If scopes are equal, containment is true\n if (haveEqualScopes(pair)) return true;\n\n // Special handling for variables\n if (symbolA.isVariable() && symbolB.isVariable()) {\n return checkVariableScopeContainment(pair);\n }\n\n // General scope containment logic\n return checkGeneralScopeContainment(pair);\n};\n\n// Main scope equality checker\nexport const equalSymbolScopes = (symbolA: FishSymbol, symbolB: FishSymbol): boolean => {\n return haveEqualScopes({ a: symbolA, b: symbolB });\n};\n\nexport const isFishSymbol = (obj: unknown): obj is FishSymbol => {\n return typeof obj === 'object'\n && obj !== null\n && 'name' in obj\n && 'fishKind' in obj\n && 'uri' in obj\n && 'node' in obj\n && 'focusedNode' in obj\n && 'scope' in obj\n && 'children' in obj\n && typeof (obj as any).name === 'string'\n && typeof (obj as any).uri === 'string'\n && Array.isArray((obj as any).children);\n};\n\nexport const fishSymbolNameEqualsNodeText = (symbol: FishSymbol, node: SyntaxNode): boolean => {\n // Check if the symbol's name matches the text of the node\n return symbol.name === node.text;\n};\n"
},
{
"path": "src/parsing/export.ts",
"content": "import { SyntaxNode } from 'web-tree-sitter';\nimport { Range } from 'vscode-languageserver';\nimport { isCommandWithName, isConcatenation, isString } from '../utils/node-types';\nimport { LspDocument } from '../document';\nimport { FishSymbol } from './symbol';\nimport { DefinitionScope } from '../utils/definition-scope';\nimport { getRange } from '../utils/tree-sitter';\nimport { md } from '../utils/markdown-builder';\nimport { uriToReadablePath } from '../utils/translation';\nimport { Option } from './options';\n\n/**\n * Checks if a node is an export command definition\n */\nexport function isExportDefinition(node: SyntaxNode): boolean {\n return isCommandWithName(node, 'export') && node.children.length >= 2;\n}\n/**\n * Checks if a node is a variable name in an export statement (NAME=VALUE)\n */\nexport function isExportVariableDefinitionName(node: SyntaxNode): boolean {\n if (isString(node) || isConcatenation(node)) return false;\n if (!node.parent) return false;\n // concatenated node is an export with `=`\n const isConcatenated = isConcatenation(node.parent);\n // if the parent is a concatenation node, then move up to it's parent\n let parentNode = node.parent;\n // if that is the case, then we need to move up 1 more parent\n if (isConcatenated) parentNode = parentNode.parent as SyntaxNode;\n if (!parentNode || !isCommandWithName(parentNode, 'export')) return false;\n // since there is two possible cases, handle concatenated and non-concatenated differently\n const firstChild = isConcatenated\n ? parentNode.firstNamedChild\n : parentNode.firstChild;\n // skip `export` named node, since it's not the alias name\n if (firstChild && firstChild.equals(node)) return false;\n const args = parentNode.childrenForFieldName('argument');\n // first element is args is the export name\n const exportName = isConcatenated\n ? args.at(0)?.firstChild\n : args.at(0);\n return !!exportName && exportName.equals(node);\n}\n\ntype ExtractedExportVariable = {\n name: string;\n value: string;\n nameRange: Range;\n};\n\nexport function findVariableDefinitionNameNode(node: SyntaxNode): {\n nameNode?: SyntaxNode;\n valueNode?: SyntaxNode;\n isConcatenation: boolean;\n isValueString: boolean;\n isNonEscaped: boolean;\n} {\n function getName(node: SyntaxNode): SyntaxNode | undefined {\n let current: SyntaxNode | null = node;\n while (current && current.type === 'concatenation') {\n current = current.firstChild;\n }\n if (!current) return undefined;\n return current;\n }\n\n function getValue(node: SyntaxNode): SyntaxNode | undefined {\n let current: SyntaxNode | null = node;\n while (current && current.type === 'concatenation') {\n current = current.lastChild;\n }\n if (!current) return undefined;\n return current;\n }\n\n let isConcatenation = false;\n const nameNode = getName(node);\n const valueNode = getValue(node);\n const isValueString = !!valueNode && isString(valueNode);\n const isNonEscaped = !!valueNode && !!nameNode && nameNode.equals(valueNode);\n\n if (!nameNode || !valueNode) {\n return {\n nameNode,\n valueNode,\n isConcatenation: false,\n isValueString,\n isNonEscaped,\n };\n }\n if (nameNode?.equals(valueNode)) {\n return {\n nameNode,\n valueNode,\n isConcatenation,\n isValueString,\n isNonEscaped,\n };\n }\n isConcatenation = true;\n return {\n nameNode,\n valueNode,\n isConcatenation,\n isValueString,\n isNonEscaped,\n };\n}\n\n/**\n * Extracts variable information from an export definition\n */\nexport function extractExportVariable(node: SyntaxNode): ExtractedExportVariable | null {\n const argument = node.firstChild?.nextNamedSibling;\n if (!argument) {\n return null;\n }\n\n // Split on the first '=' to get name and value\n const [name, ...valueParts] = argument.text.split('=') as [string, ...string[]];\n const value = valueParts.join('='); // Rejoin in case value contains '='\n\n // Calculate range for just the name part\n const nameStart = {\n line: argument.startPosition.row,\n character: argument.startPosition.column,\n };\n\n const nameEnd = {\n line: nameStart.line,\n character: nameStart.character + name.length,\n };\n\n return { name, value, nameRange: Range.create(nameStart, nameEnd) };\n}\n\nexport function buildExportDetail(doc: LspDocument, commandNode: SyntaxNode, variableDefinitionNode: SyntaxNode) {\n const commandText = commandNode.text;\n\n const extracted = extractExportVariable(variableDefinitionNode);\n if (!extracted) return '';\n const { name, value } = extracted;\n\n // Create a detail string with the command and variable definition\n const detail = [\n `${md.bold('(variable)')} ${md.inlineCode(name)}`,\n `${md.italic('globally')} scoped, ${md.italic('exported')}`,\n `located in file: ${md.inlineCode(uriToReadablePath(doc.uri))}`,\n md.separator(),\n md.codeBlock('fish', commandText),\n md.separator(),\n md.codeBlock('fish', `set -gx ${name} ${value}`),\n ].join(md.newline());\n return detail;\n}\n\n/**\n * Process an export command to create a FishSymbol\n */\nexport function processExportCommand(document: LspDocument, node: SyntaxNode, children: FishSymbol[] = []): FishSymbol[] {\n if (!isExportDefinition(node)) return [];\n\n // Get the second argument (the variable assignment part)\n const args = node.namedChildren.slice(1); // Skip 'export' command name\n if (args.length === 0) return [];\n\n const argNode = args[0]!;\n\n // Find the variable definition in the command's arguments\n const found = findVariableDefinitionNameNode(argNode);\n\n const varDefNode = found?.nameNode;\n if (!found || !varDefNode) return [];\n\n const {\n name,\n nameRange,\n } = extractExportVariable(node) as ExtractedExportVariable;\n\n // Get the scope - export always creates global exported variables\n const scope = DefinitionScope.create(node.parent || node, 'global');\n\n // The detail will be formatted by FishSymbol.setupDetail()\n const detail = buildExportDetail(document, node, found.nameNode!);\n\n // Create a FishSymbol for the export definition - using 'SET' fishKind\n // since export is effectively an alias for 'set -gx'\n return [\n FishSymbol.fromObject({\n name,\n node,\n focusedNode: varDefNode,\n range: getRange(node),\n selectionRange: nameRange,\n fishKind: 'EXPORT', // Using SET since export is equivalent to 'set -gx'\n document,\n uri: document.uri,\n detail,\n scope,\n // this is so that we always see that export variables are global and exported\n options: [Option.create('-g', '--global'), Option.create('-x', '--export')],\n children,\n }),\n ];\n}\n"
},
{
"path": "src/parsing/for.ts",
"content": "import { SyntaxNode } from 'web-tree-sitter';\nimport { FishSymbol } from './symbol';\nimport { DefinitionScope } from '../utils/definition-scope';\nimport { LspDocument } from '../document';\n\n/**\n * Checks if a SyntaxNode is a `for` loop definition name.\n *\n * ```fish\n * for i in (seq 1 10);\n * # ^_________________ `i` is the for loop definition name\n * end\n * ```\n *\n * @param node - The SyntaxNode to check (a 'variable_name' with a parent `for_statement`).\n * @return {boolean} - True if the node is a `for` loop definition name, false otherwise.\n */\nexport function isForVariableDefinitionName(node: SyntaxNode): boolean {\n if (node.parent && node.parent.type === 'for_statement') {\n return !!node.parent.firstNamedChild &&\n node.parent.firstNamedChild.type === 'variable_name' &&\n node.parent.firstNamedChild.equals(node);\n }\n return false;\n}\n\n/**\n * Create a FishSymbol for a `for` loop definition name.\n *\n * NOTE: `for ...` is not guaranteed to be processed into a FishSymbol,\n * instead we only consider `for variable_name in ...` as a definition.\n *\n * @param document - The LspDocument containing the node.\n * @param node - The SyntaxNode representing the `for` loop definition name.\n * @param children - Optional array of FishSymbol children.\n * @return An array containing a single FishSymbol for the `for` loop definition.\n */\nexport function processForDefinition(document: LspDocument, node: SyntaxNode, children: FishSymbol[] = []) {\n const modifier = 'local';\n const definitionNode = node.firstNamedChild!;\n const definitionScope = DefinitionScope.create(node, modifier);\n return [\n FishSymbol.create(\n definitionNode.text,\n node,\n definitionNode,\n 'FOR',\n document,\n document.uri,\n node.text,\n definitionScope,\n [],\n children,\n ),\n ];\n}\n"
},
{
"path": "src/parsing/function.ts",
"content": "import { SyntaxNode } from 'web-tree-sitter';\nimport { findOptionsSet, Option, OptionValueMatch } from './options';\nimport { FishSymbol } from './symbol';\nimport { LspDocument } from '../document';\nimport { findParentWithFallback, isEscapeSequence, isNewline, isString } from '../utils/node-types';\nimport { PrebuiltDocumentationMap } from '../utils/snippets';\nimport { DefinitionScope } from '../utils/definition-scope';\nimport { isAutoloadedUriLoadsFunctionName } from '../utils/translation';\nimport { getRange } from '../utils/tree-sitter';\nimport { md } from '../utils/markdown-builder';\nimport { FishSymbolKindMap } from './symbol-kinds';\n\nexport const FunctionOptions = [\n Option.create('-a', '--argument-names').withMultipleValues(),\n Option.create('-d', '--description').withValue(),\n Option.create('-w', '--wraps').withValue(),\n Option.create('-e', '--on-event').withValue(),\n Option.create('-v', '--on-variable').withValue(),\n Option.create('-j', '--on-job-exit').withValue(),\n Option.create('-p', '--on-process-exit').withValue(),\n Option.create('-s', '--on-signal').withValue(),\n Option.create('-S', '--no-scope-shadowing'),\n Option.create('-V', '--inherit-variable').withValue(),\n];\n\nexport const FunctionEventOptions = [\n Option.create('-e', '--on-event').withValue(),\n Option.create('-v', '--on-variable').withValue(),\n Option.create('-j', '--on-job-exit').withValue(),\n Option.create('-p', '--on-process-exit').withValue(),\n Option.create('-s', '--on-signal').withValue(),\n];\n\nexport const FunctionVariableOptions = FunctionOptions.filter(option => option.equalsRawOption('-a', '--argument-names', '-V', '--inherit-variable', '-v', '--on-variable'));\n\nfunction isFunctionDefinition(node: SyntaxNode) {\n return node.type === 'function_definition';\n}\n\n/**\n * Util to find all the arguments of a function_definition node\n *\n * function foo -a bar baz -V foobar -d '...' -w '...' --on-event '...'\n * ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^\n * all of these nodes would be returned in the SyntaxNode[] array\n * @param node the function_definition node\n * @returns SyntaxNode[] of all the arguments to the function_definition\n */\nexport function findFunctionDefinitionChildren(node: SyntaxNode) {\n return node.childrenForFieldName('option').filter(n => !isEscapeSequence(n) && !isNewline(n));\n}\n\n/**\n * Get argv definition for fish shell script files (non auto-loaded files)\n */\nexport function processArgvDefinition(document: LspDocument, node: SyntaxNode) {\n if (!document.isAutoloaded() && node.type === 'program') {\n return [\n FishSymbol.fromObject({\n name: 'argv',\n node: node,\n focusedNode: node.firstChild!,\n fishKind: FishSymbolKindMap.variable,\n document,\n uri: document.uri,\n detail: PrebuiltDocumentationMap.getByName('argv').pop()?.description || 'the list of arguments passed to the function',\n scope: DefinitionScope.create(node, 'local'),\n selectionRange: {\n start: { line: 0, character: 0 },\n end: { line: 0, character: 0 },\n },\n range: getRange(node),\n options: [Option.create('-l', '--local')],\n children: [],\n }),\n ];\n }\n return [];\n}\n\n/**\n * checks if a node is the function name of a function definition\n * function foo\n * ^--- here\n */\nexport function isFunctionDefinitionName(node: SyntaxNode) {\n if (!node.parent || !isFunctionDefinition(node.parent)) return false;\n if (isString(node)) return false;\n return !!node.parent.firstNamedChild && node.parent.firstNamedChild.equals(node);\n}\n\n/**\n * checks if a node is the variable name of a function definition\n * function foo --argument-names bar baz --inherit-variable foobar\n * ^ ^ ^\n * | | |\n * Could be any of these nodes above\n * Currently doesn't check for `--on-variable`, because it should be inherited\n */\nexport function isFunctionVariableDefinitionName(node: SyntaxNode) {\n if (!node.parent || !isFunctionDefinition(node.parent)) return false;\n const { variableNodes } = findFunctionOptionNamedArguments(node.parent);\n const definitionNode = variableNodes.find(n => n.equals(node));\n return !!definitionNode && definitionNode.equals(node);\n}\n\n/**\n * Find all the function_definition variables/events that are defined in the function header\n *\n * The `flagsSet` property contains all the nodes that were found to be variable names,\n * with the flag that was used to define them.\n *\n * @param node the function_definition node\n * @returns Object containing the defined SyntaxNode[] and OptionValueMatch[] flags set\n */\nexport function findFunctionOptionNamedArguments(node: SyntaxNode): {\n variableNodes: SyntaxNode[];\n eventNodes: SyntaxNode[];\n flagsSet: OptionValueMatch[];\n} {\n const variableNodes: SyntaxNode[] = [];\n const eventNodes: SyntaxNode[] = [];\n const focused = node.childrenForFieldName('option').filter(n => !isEscapeSequence(n) && !isNewline(n));\n const flagsSet = findOptionsSet(focused, FunctionOptions);\n for (const flag of flagsSet) {\n const { option, value: focused } = flag;\n switch (true) {\n case option.isOption('-a', '--argument-names'):\n case option.isOption('-V', '--inherit-variable'):\n // case option.isOption('-v', '--on-variable'):\n variableNodes.push(focused);\n break;\n case option.isOption('-e', '--on-event'):\n eventNodes.push(focused);\n break;\n default:\n break;\n }\n }\n return {\n variableNodes,\n eventNodes,\n flagsSet,\n };\n}\n\n/**\n * Process a function definition node and return the corresponding FishSymbol[]\n * for the function and its arguments. Includes argv as a child, along with any\n * flags that create function scoped variables + any children nodes are stored as well.\n */\nexport function processFunctionDefinition(document: LspDocument, node: SyntaxNode, children: FishSymbol[] = []) {\n if (!isFunctionDefinition(node)) return [];\n\n const autoloadScope = isAutoloadedUriLoadsFunctionName(document);\n\n const focusedNode = node.firstNamedChild!;\n\n if (!focusedNode) return [];\n\n const scopeModifier = autoloadScope(focusedNode) ? 'global' : 'local';\n const scopeParentNode = findParentWithFallback(node, (n) => !n.equals(node) && isFunctionDefinition(n));\n const focused = node.childrenForFieldName('option').filter(n => !isEscapeSequence(n) && !isNewline(n));\n\n const functionSymbol = FishSymbol.create(\n focusedNode.text,\n node,\n focusedNode,\n FishSymbolKindMap.function,\n document,\n document.uri,\n node.text,\n DefinitionScope.create(scopeParentNode, scopeModifier),\n findOptionsSet(focused, FunctionOptions)?.map(opt => opt.option) || [],\n );\n\n functionSymbol.addChildren(\n FishSymbol.create(\n 'argv',\n node,\n node.firstNamedChild!,\n FishSymbolKindMap.function_variable,\n document,\n document.uri,\n PrebuiltDocumentationMap.getByName('argv').pop()?.description || 'the list of arguments passed to the function',\n DefinitionScope.create(node, 'local'),\n [Option.create('-l', '--local')],\n ),\n );\n\n if (!focused) return [functionSymbol];\n\n const { flagsSet } = findFunctionOptionNamedArguments(node);\n for (const flag of flagsSet) {\n const { option, value: focused } = flag;\n switch (true) {\n case option.isOption('-a', '--argument-names'):\n case option.isOption('-V', '--inherit-variable'):\n // case option.isOption('-v', '--on-variable'):\n functionSymbol.addChildren(\n FishSymbol.create(\n focused.text,\n node,\n focused,\n FishSymbolKindMap.function_variable,\n document,\n document.uri,\n focused.text,\n DefinitionScope.create(node, 'local'),\n [option],\n ),\n );\n break;\n case option.isOption('-e', '--on-event'):\n functionSymbol.addChildren(\n FishSymbol.create(\n focused.text,\n node,\n focused,\n FishSymbolKindMap.function_event,\n document,\n document.uri,\n [\n `${md.boldItalic('Generic Event:')} ${md.inlineCode(focused.text)}`,\n `${md.boldItalic('Event Handler:')} ${md.inlineCode(focusedNode.text)}`,\n md.separator(),\n md.codeBlock('fish', [\n `### function definition: '${focusedNode.text}'`,\n focusedNode?.parent?.text.toString(),\n '',\n '### Use the builtin `emit`, to fire this event:',\n `emit ${focused.text.toString()}`,\n `emit ${focused.text.toString()} with arguments # Specifies \\`$argv\\` to the event handler`,\n ].join('\\n')),\n md.separator(),\n md.boldItalic('SEE ALSO:'),\n ' • Emit Events: https://fishshell.com/docs/current/cmds/emit.html',\n ' • Emit Handling: https://fishshell.com/docs/current/language.html#event',\n\n ].join(md.newline()),\n DefinitionScope.create(node.tree.rootNode, 'global'),\n [option],\n ),\n );\n break;\n default:\n break;\n }\n }\n return [functionSymbol.addChildren(...children)];\n}\n"
},
{
"path": "src/parsing/inline-variable.ts",
"content": "import { SyntaxNode } from 'web-tree-sitter';\nimport { isCommand, isCommandName } from '../utils/node-types';\nimport { FishSymbol } from './symbol';\nimport { Position, Range } from 'vscode-languageserver';\nimport { LspDocument } from '../document';\nimport { getRange } from '../utils/tree-sitter';\nimport { DefinitionScope } from '../utils/definition-scope';\n\n/**\n * Parse command-scoped environment variable exports from Fish shell syntax.\n *\n * Examples:\n * - `NVIM_APPNAME=nvim-lua nvim`\n * - `DEBUG=1 npm test`\n * - `PATH=/usr/local/bin:$PATH command`\n *\n * These are temporary environment variable assignments that only apply\n * to the specific command being executed.\n */\n\n/**\n * Check if a command node contains inline environment variable assignments\n */\nexport function hasInlineVariables(commandNode: SyntaxNode): boolean {\n if (!isCommand(commandNode)) return false;\n\n // Look for assignment patterns in command arguments\n for (let i = 0; i < commandNode.namedChildCount; i++) {\n const child = commandNode.namedChild(i);\n if (child && isInlineVariableAssignment(child)) {\n return true;\n }\n }\n\n return false;\n}\n\n/**\n * Check if a node represents an inline variable assignment (VAR=value)\n */\nexport function isInlineVariableAssignment(node: SyntaxNode): boolean {\n if (node.type !== 'word' && node.type !== 'concatenation') return false;\n\n // Check if the text contains an assignment pattern\n const text = node.text;\n const assignmentMatch = text.match(/^([A-Z_][A-Z0-9_]*)=(.*)$/);\n\n return assignmentMatch !== null;\n}\n\n/**\n * Extract variable name and value from an inline assignment node\n */\nexport function parseInlineVariableAssignment(node: SyntaxNode): { name: string; value: string; } | null {\n if (!isInlineVariableAssignment(node)) return null;\n\n const text = node.text;\n const assignmentMatch = text.match(/^([A-Z_][A-Z0-9_]*)=(.*)$/);\n\n if (!assignmentMatch || !assignmentMatch[1] || assignmentMatch[2] === undefined) return null;\n\n return {\n name: assignmentMatch[1],\n value: assignmentMatch[2],\n };\n}\n\n/**\n * Extract all inline variable assignments from a command node\n */\nexport function processInlineVariables(document: LspDocument, commandNode: SyntaxNode): FishSymbol[] {\n if (!isCommand(commandNode)) return [];\n\n const symbols: FishSymbol[] = [];\n\n // Find the actual command name and variable assignments\n // Inline variables come before the command name: VAR1=val1 VAR2=val2 command args\n let commandNameNode: SyntaxNode | null = null;\n const variableNodes: SyntaxNode[] = [];\n\n for (let i = 0; i < commandNode.namedChildCount; i++) {\n const child = commandNode.namedChild(i);\n if (!child) continue;\n\n if (isInlineVariableAssignment(child)) {\n // Only collect variables that come before the command name\n if (!commandNameNode) {\n variableNodes.push(child);\n }\n } else if (!commandNameNode && isCommandName(child)) {\n commandNameNode = child;\n // Don't break here - continue to process remaining args if needed\n }\n }\n\n // Create FishSymbol for each inline variable\n for (const varNode of variableNodes) {\n const assignment = parseInlineVariableAssignment(varNode);\n if (!assignment) continue;\n\n const startPos = Position.create(varNode.startPosition.row, varNode.startPosition.column);\n // const endPos = Position.create(varNode.endPosition.row, varNode.endPosition.column);\n\n // Calculate the range for just the variable name (before the =)\n const nameEndColumn = varNode.startPosition.column + assignment.name.length;\n const nameRange = Range.create(\n startPos,\n Position.create(varNode.startPosition.row, nameEndColumn),\n );\n\n // Create a basic scope for command-level variables\n const scope = DefinitionScope.create(commandNode, 'local');\n\n const symbol = FishSymbol.fromObject({\n name: assignment.name,\n document,\n node: commandNode,\n focusedNode: varNode,\n detail: `Command environment variable: ${assignment.name}=${assignment.value}`,\n fishKind: 'INLINE_VARIABLE',\n range: getRange(varNode),\n selectionRange: nameRange,\n scope,\n children: [],\n });\n\n symbols.push(symbol);\n }\n\n return symbols;\n}\n\n/**\n * Find all inline variable assignments in a syntax tree\n */\nexport function findAllInlineVariables(document: LspDocument, tree: SyntaxNode): FishSymbol[] {\n const symbols: FishSymbol[] = [];\n\n function walkTree(node: SyntaxNode) {\n if (isCommand(node) && hasInlineVariables(node)) {\n symbols.push(...processInlineVariables(document, node));\n }\n\n for (let i = 0; i < node.namedChildCount; i++) {\n const child = node.namedChild(i);\n if (child) {\n walkTree(child);\n }\n }\n }\n\n walkTree(tree);\n return symbols;\n}\n\n/**\n * Get completion suggestions for inline variable names\n * Returns common environment variables that are often used inline\n */\nexport function getInlineVariableCompletions(): string[] {\n return [\n 'DEBUG',\n 'NODE_ENV',\n 'PATH',\n 'HOME',\n 'USER',\n 'SHELL',\n 'LANG',\n 'LC_ALL',\n 'TERM',\n 'DISPLAY',\n 'NVIM_APPNAME',\n 'EDITOR',\n 'PAGER',\n 'BROWSER',\n 'HTTP_PROXY',\n 'HTTPS_PROXY',\n 'NO_PROXY',\n ];\n}\n"
},
{
"path": "src/parsing/nested-strings.ts",
"content": "import { SyntaxNode } from 'web-tree-sitter';\nimport { DocumentUri, Range, Location } from 'vscode-languageserver';\nimport { getRange } from '../utils/tree-sitter';\n\n/**\n * Configuration for command extraction\n */\nexport interface ExtractConfig {\n /** Whether to parse command substitutions like $(cmd) */\n readonly parseCommandSubstitutions: boolean;\n /** Whether to parse parenthesized expressions like (cmd; and cmd2) */\n readonly parseParenthesized: boolean;\n /** Whether to remove fish keywords and operators */\n readonly cleanKeywords: boolean;\n}\n\n/**\n * Command reference with location information\n */\nexport interface CommandReference {\n /** The extracted command name */\n readonly command: string;\n /** Location in the document */\n readonly location: Location;\n}\n\nconst DEFAULT_CONFIG: ExtractConfig = {\n parseCommandSubstitutions: true,\n parseParenthesized: true,\n cleanKeywords: true,\n};\n\n/**\n * Fish shell keywords and operators that should be filtered out\n */\nconst FISH_KEYWORDS = new Set([\n 'and', 'or', 'not', 'begin', 'end', 'if', 'else', 'switch', 'case',\n 'for', 'in', 'while', 'function', 'return', 'break', 'continue',\n 'set', 'test', 'true', 'false',\n]);\n\nconst FISH_OPERATORS = new Set([\n '&&', '||', '|', ';', '&', '>', '<', '>>', '<<', '>&', '<&',\n '2>', '2>>', '2>&1', '1>&2', '/dev/null',\n]);\n\n/**\n * Extract commands from fish shell string nodes\n */\nexport function extractCommands(\n node: SyntaxNode,\n config: ExtractConfig = DEFAULT_CONFIG,\n): string[] {\n if (!node.text?.trim()) return [];\n\n const nodeText = node.text;\n\n // Handle option arguments like --wraps=command\n const optionCommand = parseOptionArgument(nodeText);\n if (optionCommand) {\n return [optionCommand];\n }\n\n const cleanedText = cleanQuotes(nodeText);\n const commands = new Set();\n\n // Always parse direct commands first\n const directCommands = parseDirectCommands(cleanedText, config);\n directCommands.forEach(cmd => commands.add(cmd));\n\n // Parse command substitutions: $(cmd args)\n if (config.parseCommandSubstitutions) {\n const substitutionCommands = parseCommandSubstitutions(cleanedText);\n substitutionCommands.forEach(cmd => commands.add(cmd));\n }\n\n // Parse parenthesized expressions: (cmd; and cmd2)\n if (config.parseParenthesized) {\n const parenthesizedCommands = parseParenthesizedExpressions(cleanedText);\n parenthesizedCommands.forEach(cmd => commands.add(cmd));\n }\n\n return Array.from(commands).filter(cmd => cmd.length > 0);\n}\n\n/**\n * Extract command references with precise location information\n */\nexport function extractCommandLocations(\n node: SyntaxNode,\n documentUri: DocumentUri,\n config: ExtractConfig = DEFAULT_CONFIG,\n): CommandReference[] {\n if (!node.text?.trim()) return [];\n\n const nodeRange = getRange(node);\n const nodeText = node.text;\n // Handle option arguments like --wraps=command\n const optionCommand = parseOptionArgument(nodeText);\n if (optionCommand) {\n const offset = nodeText.indexOf(optionCommand);\n return [{\n command: optionCommand,\n location: Location.create(\n documentUri,\n createPreciseRange(optionCommand, offset, nodeRange),\n ),\n }];\n }\n\n const cleanedText = cleanQuotes(nodeText);\n const quoteOffset = getQuoteOffset(nodeText);\n\n return findCommandsWithOffsets(cleanedText, config)\n .map(({ command, offset }) => ({\n command,\n location: Location.create(\n documentUri,\n createPreciseRange(command, offset + quoteOffset, nodeRange),\n ),\n }));\n}\n\n/**\n * Extract locations for a specific command name\n */\nexport function extractMatchingCommandLocations(\n symbol: { name: string; },\n node: SyntaxNode,\n documentUri: DocumentUri,\n config: ExtractConfig = DEFAULT_CONFIG,\n): Location[] {\n return extractCommandLocations(node, documentUri, config)\n .filter(ref => ref.command === symbol.name)\n .map(ref => ref.location);\n}\n\n/**\n * Remove surrounding quotes and return offset adjustment\n */\nfunction cleanQuotes(input: string): string {\n const trimmed = input.trim();\n if (trimmed.startsWith('\"') && trimmed.endsWith('\"') ||\n trimmed.startsWith(\"'\") && trimmed.endsWith(\"'\")) {\n return trimmed.slice(1, -1);\n }\n return trimmed;\n}\n\n/**\n * Get the offset adjustment for quotes\n */\nfunction getQuoteOffset(input: string): number {\n const trimmed = input.trim();\n if (trimmed.startsWith('\"') && trimmed.endsWith('\"') ||\n trimmed.startsWith(\"'\") && trimmed.endsWith(\"'\")) {\n return 1; // Account for opening quote\n }\n return 0;\n}\n\n/**\n * Find all commands with their precise offsets in the text\n */\nfunction findCommandsWithOffsets(\n text: string,\n config: ExtractConfig,\n): Array<{ command: string; offset: number; }> {\n const results: Array<{ command: string; offset: number; }> = [];\n\n // Always parse direct commands first\n results.push(...findDirectCommandOffsets(text, config));\n\n // Parse command substitutions\n if (config.parseCommandSubstitutions) {\n results.push(...findCommandSubstitutionOffsets(text));\n }\n\n // Parse parenthesized expressions\n if (config.parseParenthesized) {\n results.push(...findParenthesizedCommandOffsets(text));\n }\n\n return results;\n}\n\n/**\n * Find command substitutions with offsets\n */\nfunction findCommandSubstitutionOffsets(text: string): Array<{ command: string; offset: number; }> {\n const results: Array<{ command: string; offset: number; }> = [];\n const regex = /\\$\\(([^)]+)\\)/g;\n let match: RegExpExecArray | null;\n\n while ((match = regex.exec(text)) !== null) {\n const commandText = match[1];\n const innerOffset = match.index + 2; // Skip '$('\n\n if (commandText?.trim()) {\n const firstCommand = getFirstCommand(commandText);\n if (firstCommand) {\n results.push({\n command: firstCommand,\n offset: innerOffset + commandText.indexOf(firstCommand),\n });\n }\n }\n }\n\n return results;\n}\n\n/**\n * Find parenthesized commands with offsets\n */\nfunction findParenthesizedCommandOffsets(text: string): Array<{ command: string; offset: number; }> {\n const results: Array<{ command: string; offset: number; }> = [];\n const stack: number[] = [];\n let start = -1;\n\n for (let i = 0; i < text.length; i++) {\n if (text[i] === '(') {\n if (stack.length === 0) start = i;\n stack.push(i);\n } else if (text[i] === ')' && stack.length > 0) {\n stack.pop();\n\n if (stack.length === 0 && start !== -1) {\n const innerText = text.slice(start + 1, i);\n const innerOffset = start + 1;\n\n if (innerText.trim()) {\n const commands = extractCommandsFromText(innerText);\n for (const command of commands) {\n const commandOffset = innerText.indexOf(command);\n if (commandOffset !== -1) {\n results.push({\n command,\n offset: innerOffset + commandOffset,\n });\n }\n }\n }\n start = -1;\n }\n }\n }\n\n return results;\n}\n\n/**\n * Find direct commands with offsets\n */\nfunction findDirectCommandOffsets(\n text: string,\n config: ExtractConfig,\n): Array<{ command: string; offset: number; }> {\n const results: Array<{ command: string; offset: number; }> = [];\n const statements = text.split(/[;&|]+/);\n let currentOffset = 0;\n\n for (const statement of statements) {\n const trimmedStatement = statement.trim();\n const statementStart = text.indexOf(trimmedStatement, currentOffset);\n\n if (trimmedStatement) {\n const tokens = tokenizeStatement(trimmedStatement);\n\n // Filter tokens if cleaning is enabled\n const relevantTokens = config.cleanKeywords\n ? tokens.filter(token => !FISH_KEYWORDS.has(token) && !FISH_OPERATORS.has(token))\n : tokens;\n\n // Find offset for each relevant token\n for (const token of relevantTokens) {\n if (token && !isNumeric(token) && token.length > 1) {\n const tokenOffset = trimmedStatement.indexOf(token);\n if (tokenOffset !== -1) {\n results.push({\n command: token,\n offset: statementStart + tokenOffset,\n });\n }\n }\n }\n }\n\n currentOffset = statementStart + statement.length;\n }\n\n return results;\n}\n\n/**\n * Get the first command from a text string\n */\nfunction getFirstCommand(text: string): string | null {\n const tokens = tokenizeStatement(text);\n return tokens.length > 0 && tokens[0] && tokens[0].length > 1 ? tokens[0] : null;\n}\n\n/**\n * Extract individual commands from a text string\n */\nfunction extractCommandsFromText(input: string, cleanKeywords = true): string[] {\n const statements = input.split(/[;&|]+/)\n .map(stmt => stmt.trim())\n .filter(stmt => stmt.length > 0);\n\n const commands: string[] = [];\n\n for (const statement of statements) {\n const tokens = tokenizeStatement(statement);\n\n // Filter out fish keywords if enabled\n const filteredTokens = cleanKeywords\n ? tokens.filter(token => !FISH_KEYWORDS.has(token) && !FISH_OPERATORS.has(token))\n : tokens;\n\n // Get all potential commands from the statement\n for (const token of filteredTokens) {\n if (token && !isNumeric(token) && token.length > 1) {\n commands.push(token);\n }\n }\n }\n\n return commands;\n}\n\n/**\n * Parse command substitutions\n */\nfunction parseCommandSubstitutions(input: string): string[] {\n const commands: string[] = [];\n const regex = /\\$\\(([^)]+)\\)/g;\n let match: RegExpExecArray | null;\n\n while ((match = regex.exec(input)) !== null) {\n const commandText = match[1];\n if (commandText?.trim()) {\n commands.push(...extractCommandsFromText(commandText, true));\n }\n }\n\n return commands;\n}\n\n/**\n * Parse parenthesized expressions\n */\nfunction parseParenthesizedExpressions(input: string): string[] {\n const commands: string[] = [];\n const stack: number[] = [];\n let start = -1;\n\n for (let i = 0; i < input.length; i++) {\n if (input[i] === '(') {\n if (stack.length === 0) start = i;\n stack.push(i);\n } else if (input[i] === ')' && stack.length > 0) {\n stack.pop();\n\n if (stack.length === 0 && start !== -1) {\n const innerText = input.slice(start + 1, i);\n if (innerText.trim()) {\n commands.push(...extractCommandsFromText(innerText, true));\n }\n start = -1;\n }\n }\n }\n\n return commands;\n}\n\n/**\n * Parse option arguments like --wraps=command, --command=cmd, etc.\n */\nfunction parseOptionArgument(text: string): string | null {\n // Match patterns like --wraps=command, --command=cmd, -c=cmd\n const optionArgRegex = /^(?:-[a-zA-Z]|--[a-zA-Z][a-zA-Z0-9-]*)\\s*=\\s*([a-zA-Z_][a-zA-Z0-9_-]*)/;\n const match = text.match(optionArgRegex);\n\n if (match && match[1]) {\n const command = match[1].trim();\n // Only return if it looks like a valid command (not a number or single char)\n if (command.length > 1 && !isNumeric(command)) {\n return command;\n }\n }\n\n return null;\n}\n\n/**\n * Parse direct commands\n */\nfunction parseDirectCommands(input: string, config: ExtractConfig): string[] {\n return extractCommandsFromText(input, config.cleanKeywords);\n}\n\n/**\n * Tokenize a statement respecting quotes\n */\nfunction tokenizeStatement(statement: string): string[] {\n const tokens: string[] = [];\n let current = '';\n let inQuotes = false;\n let quoteChar = '';\n\n for (let i = 0; i < statement.length; i++) {\n const char = statement[i];\n if (!char) continue;\n\n if (!inQuotes && (char === '\"' || char === \"'\")) {\n inQuotes = true;\n quoteChar = char;\n current += char;\n } else if (inQuotes && char === quoteChar) {\n inQuotes = false;\n current += char;\n quoteChar = '';\n } else if (!inQuotes && /\\s/.test(char)) {\n if (current.trim()) {\n tokens.push(current.trim());\n current = '';\n }\n } else {\n current += char;\n }\n }\n\n if (current.trim()) {\n tokens.push(current.trim());\n }\n\n return tokens;\n}\n\n/**\n * Create a precise range for a command at a specific offset\n */\nfunction createPreciseRange(command: string, offset: number, nodeRange: Range): Range {\n const startChar = nodeRange.start.character + offset;\n\n return {\n start: {\n line: nodeRange.start.line,\n character: startChar,\n },\n end: {\n line: nodeRange.start.line,\n character: startChar + command.length,\n },\n };\n}\n\n/**\n * Check if a string is numeric\n */\nfunction isNumeric(str: string): boolean {\n return /^[0-9]+$/.test(str);\n}\n"
},
{
"path": "src/parsing/options.ts",
"content": "import { SyntaxNode } from 'web-tree-sitter';\nimport { isLongOption, isOption, isShortOption } from '../utils/node-types';\nimport { getRange } from '../utils/tree-sitter';\nimport * as LSP from 'vscode-languageserver';\n\n/**\n * Type definitions to allow us for checking single character (short) flags.\n */\ntype AlphaLowercaseChar = 'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'g' | 'h' | 'i' | 'j' | 'k' | 'l' | 'm' | 'n' | 'o' | 'p' | 'q' | 'r' | 's' | 't' | 'u' | 'v' | 'w' | 'x' | 'y' | 'z';\ntype AlphaUppercaseChar = 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' | 'I' | 'J' | 'K' | 'L' | 'M' | 'N' | 'O' | 'P' | 'Q' | 'R' | 'S' | 'T' | 'U' | 'V' | 'W' | 'X' | 'Y' | 'Z';\ntype AlphaChar = AlphaLowercaseChar | AlphaUppercaseChar;\ntype DigitChar = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9';\ntype ExtraChar = '?' | '!' | '@' | '$' | '%' | '^' | '&' | '*' | '(' | ')' | '+' | '=' | '{' | '}' | '[' | ']' | '|' | ';' | ':' | '\"' | \"'\" | '<' | '>' | ',' | '.' | '/' | '\\\\' | '~' | '`';\ntype Character = AlphaChar | DigitChar | ExtraChar;\n\n/**\n * flags types using template literals to ensure the following type safetry:\n * - ShortFlag is max a single character.\n * - UnixFlag can be single or multiple characters, but must start with a single `-`.\n * - LongFlag must start with `--` and can be multiple characters.\n */\nexport type ShortFlag = `-${Character}`;\nexport type UnixFlag = `-${string}`;\nexport type LongFlag = `--${string}`;\nexport type Flag = ShortFlag | UnixFlag | LongFlag;\n\n/**\n * Type Guard for converting a option string into the correct flag type.\n */\nexport const stringIsShortFlag = (str: string): str is ShortFlag => str.startsWith('-') && str.length === 2;\nexport const stringIsLongFlag = (str: string): str is LongFlag => str.startsWith('--');\nexport const stringIsUnixFlag = (str: string): str is UnixFlag => str.startsWith('-') && str.length > 2 && !str.startsWith('--');\n\nexport class Option {\n public shortOptions: ShortFlag[] = [];\n public unixOptions: UnixFlag[] = [];\n public longOptions: LongFlag[] = [];\n private requiresArgument: boolean = false;\n private acceptsMultipleArguments: boolean = false;\n private optionalArgument: boolean = false;\n\n static create(shortOption: ShortFlag | '', longOption: LongFlag | ''): Option {\n const option = new Option();\n if (shortOption) {\n option.shortOptions.push(shortOption);\n }\n if (longOption) {\n option.longOptions.push(longOption);\n }\n return option;\n }\n\n static long(longOption: LongFlag): Option {\n const option = new Option();\n option.longOptions.push(longOption);\n return option;\n }\n\n static short(shortOption: ShortFlag): Option {\n const option = new Option();\n option.shortOptions.push(shortOption);\n return option;\n }\n\n static unix(unixOption: UnixFlag): Option {\n const option = new Option();\n option.unixOptions.push(unixOption);\n return option;\n }\n\n static fromRaw(...str: string[]) {\n const option = new Option();\n for (const s of str) {\n if (stringIsLongFlag(s)) {\n option.longOptions.push(s);\n } else if (stringIsShortFlag(s)) {\n option.shortOptions.push(s as ShortFlag);\n } else if (stringIsUnixFlag(s)) {\n option.unixOptions.push(s as UnixFlag);\n }\n }\n return option;\n }\n\n addUnixFlag(...options: UnixFlag[]): Option {\n this.unixOptions.push(...options);\n return this;\n }\n\n /**\n * use addUnixFlag if you want to store unix flags in this object\n */\n withAliases(...optionAlias: ShortFlag[] | LongFlag[] | string[]): Option {\n for (const alias of optionAlias) {\n if (stringIsLongFlag(alias)) {\n this.longOptions.push(alias);\n continue;\n }\n if (stringIsShortFlag(alias)) {\n this.shortOptions.push(alias as ShortFlag);\n continue;\n }\n }\n return this;\n }\n\n isOption(shortOption: ShortFlag | '', longOption: LongFlag | ''): boolean {\n if (shortOption) {\n return this.shortOptions.includes(shortOption);\n } else if (longOption) {\n return this.longOptions.includes(longOption);\n }\n return false;\n }\n\n /**\n * Mark this option as requiring a value\n */\n withValue(): Option {\n this.requiresArgument = true;\n this.optionalArgument = false;\n this.acceptsMultipleArguments = false;\n return this;\n }\n\n /**\n * Mark this option as accepting an optional value\n */\n withOptionalValue(): Option {\n this.optionalArgument = true;\n this.requiresArgument = false;\n this.acceptsMultipleArguments = false;\n return this;\n }\n\n /**\n * Mark this option as accepting multiple values\n */\n withMultipleValues(): Option {\n this.acceptsMultipleArguments = true;\n this.requiresArgument = true;\n this.optionalArgument = false;\n return this;\n }\n\n /**\n * Check if this option is a boolean switch (takes no value)\n *\n * A switch is a flag that does not require a value to be set. Another common name for\n * this type of flag is a boolean flag.\n *\n * A switch is either enabled or disabled.\n *\n * You can pair this with `Option.equals(node) && Option.isSwitch()` to get the switch's found on sequence\n *\n * @returns true if the flag is a switch, if the flag requires a value to be set false.\n */\n isSwitch(): boolean {\n return !this.requiresArgument && !this.optionalArgument;\n }\n\n matchesValue(node: SyntaxNode): boolean {\n if (this.isSwitch()) {\n return false;\n }\n\n // Handle direct values (--option=value)\n if (isOption(node) && node.text.includes('=')) {\n const [flag] = node.text.split('=');\n return this.matches({ ...node, text: flag } as SyntaxNode);\n }\n\n let prev: SyntaxNode | null = node.previousSibling;\n // Handle values that follow the option\n // const prev = node.previousSibling;\n if (this.acceptsMultipleArguments) {\n while (prev) {\n if (isOption(prev) && !prev.text.includes('=')) {\n return this.matches(prev);\n }\n if (isOption(prev)) return false;\n prev = prev.previousSibling;\n }\n }\n\n return !!prev && this.matches(prev);\n }\n\n /**\n * Check if this option is present in the given node\n */\n matches(node: SyntaxNode, checkWithEquals: boolean = true): boolean {\n if (!isOption(node)) return false;\n\n const nodeText = checkWithEquals && node.text.includes('=')\n ? node.text.slice(0, node.text.indexOf('='))\n : node.text;\n\n if (isLongOption(node)) {\n return this.matchesLongFlag(nodeText);\n }\n\n if (isShortOption(node) && this.unixOptions.length >= 1) {\n return this.matchesUnixFlag(nodeText);\n }\n\n if (isShortOption(node)) {\n return this.matchesShortFlag(nodeText);\n }\n\n return false;\n }\n\n private matchesLongFlag(text: string): boolean {\n if (!text.startsWith('--')) return false;\n if (stringIsLongFlag(text)) {\n return this.longOptions.includes(text);\n }\n return false;\n }\n\n private matchesUnixFlag(text: string): boolean {\n if (stringIsUnixFlag(text) && text.length > 2) {\n return this.unixOptions.includes(text);\n }\n return false;\n }\n\n private matchesShortFlag(text: string): boolean {\n if (!text.startsWith('-') || text.startsWith('--')) return false;\n\n // Handle combined short flags like \"-abc\"\n const chars = text.slice(1).split('').map(char => `-${char}` as ShortFlag);\n return chars.some(char => this.shortOptions.includes(char));\n }\n\n equals(node: SyntaxNode, allowEquals = false): boolean {\n if (!isOption(node)) return false;\n const text = allowEquals ? node.text.slice(0, node.text.indexOf('=')) : node.text;\n if (isLongOption(node)) return this.matchesLongFlag(text);\n if (isShortOption(node) && this.unixOptions.length >= 1) return this.matchesUnixFlag(text);\n if (isShortOption(node)) return this.matchesShortFlag(text);\n return false;\n }\n\n /**\n * Warning, does not search oldUnixFlag\n */\n equalsRawOption(...rawOption: Flag[]): boolean {\n for (const option of rawOption) {\n if (stringIsLongFlag(option) && this.longOptions.includes(option)) {\n return true;\n }\n if (stringIsShortFlag(option) && this.shortOptions.includes(option)) {\n return true;\n }\n }\n return false;\n }\n\n equalsRawShortOption(...rawOption: ShortFlag[]): boolean {\n return rawOption.some(option => this.shortOptions.includes(option));\n }\n\n equalsRawLongOption(...rawOption: LongFlag[]): boolean {\n return rawOption.some(option => this.longOptions.includes(option));\n }\n\n equalsOption(other: Option): boolean {\n const flags = other.getAllFlags() as Flag[];\n return this.equalsRawOption(...flags);\n }\n\n findValueRangeAfterEquals(node: SyntaxNode): LSP.Range | null {\n if (!isOption(node)) return null;\n if (!node.text.includes('=')) return null;\n const range = getRange(node);\n if (!range) return null;\n const equalsIndex = node.text.indexOf('=');\n return LSP.Range.create(range.start.line, range.start.character + equalsIndex + 1, range.end.line, range.end.character);\n }\n\n /**\n * Checks if a `-f/--flag` if a enabled (like a boolean switch) or if it is set with a value.\n * ```\n * function foo --description 'this is a description' --no-scope-shadowing; end;\n * ```\n * ^--isSet ^--isSet\n * ^-- not set\n * @param node to check if it is set\n * @returns true if the node is set\n */\n isSet(node: SyntaxNode): boolean {\n if (isOption(node)) {\n return this.equals(node) && this.isSwitch();\n }\n return this.matchesValue(node);\n }\n\n getAllFlags(): Array {\n const result: string[] = [];\n if (this.shortOptions) result.push(...this.shortOptions);\n if (this.unixOptions) result.push(...this.unixOptions);\n if (this.longOptions) result.push(...this.longOptions);\n return result;\n }\n\n toString(): string {\n return this.getAllFlags().join(', ');\n }\n\n toName(): string {\n if (this.longOptions.length > 0) {\n return this.longOptions[0]!.replace(/^--/, '');\n }\n if (this.unixOptions.length > 0) {\n return this.unixOptions[0]!.replace(/^-/, '');\n }\n if (this.shortOptions.length > 0) {\n return this.shortOptions[0]!.replace(/^-/, '');\n }\n return '';\n }\n}\n\nexport type OptionValueMatch = {\n option: Option;\n value: SyntaxNode;\n};\n\nexport function findOptionsSet(nodes: SyntaxNode[], options: Option[]): OptionValueMatch[] {\n const result: OptionValueMatch[] = [];\n for (const node of nodes) {\n const values = options.filter(o => o.isSet(node));\n if (!values) {\n continue;\n }\n values.forEach(option => result.push({ option, value: node }));\n }\n return result;\n}\n\nexport function findOptions(nodes: SyntaxNode[], options: Option[]): { remaining: SyntaxNode[]; found: OptionValueMatch[]; unused: Option[]; } {\n const remaining: SyntaxNode[] = [];\n const found: OptionValueMatch[] = [];\n const unused = Array.from(options);\n for (const node of nodes) {\n const values = options.filter(o => o.isSet(node));\n if (values.length === 0 && !isOption(node)) {\n remaining.push(node);\n continue;\n }\n values.forEach(option => {\n unused.splice(unused.indexOf(option), 1);\n found.push({ option, value: node });\n });\n }\n return {\n remaining,\n found,\n unused,\n };\n}\n\n/**\n * Check if the node is a flag that is a part of the given option(s)\n * @param node The node to check\n * @param option The option(s) to check against\n * @returns true if the node is a flag that is a part of the given option(s)\n */\nexport function isMatchingOption(node: SyntaxNode, ...option: Option[]): boolean {\n if (!isOption(node)) return false;\n for (const opt of option) {\n if (opt.matches(node)) return true;\n }\n return false;\n}\n\n/**\n * Check if the node is a flag that is a part of the given option(s)\n */\nexport function findMatchingOptions(node: SyntaxNode, ...options: Option[]): Option | undefined {\n if (!isOption(node)) return;\n return options.find((opt: Option) => opt.matches(node));\n}\n\nexport function isMatchingOptionOrOptionValue(node: SyntaxNode, option: Option): boolean {\n if (isMatchingOption(node, option)) {\n return true;\n }\n const prevNode = node.previousNamedSibling;\n if (prevNode?.text.includes('=')) {\n return false;\n }\n if (prevNode && isMatchingOption(prevNode, option) && !isOption(node)) {\n return true;\n }\n return false;\n}\n\n/**\n * For any option passed in, check if the node is a value set on that option.\n *\n * ```fish\n * function foo --wraps=a -w='b' --wraps 'c'; end; # matches a b c\n * # ^^^^^^^^^ ^^^ ^^^\n * complete -c foo -s s -l long --wraps bar # matches: foo, s, long, bar\n * # ^^^ ^ ^^^^ ^^^\n * ```\n *\n * Useful because we can match either case where tree-sitter parse a option's values\n * • the option itself contains a value (e.g., `--wraps=a`, WHEN A `=` SIGN IS PRESENT)\n * • the value, where the previous named silbing matches the option\n *\n * @param node The node to check\n * @param options The options to check against\n *\n * @returns true if the node is a value set on any of the given option(s)\n */\nexport function isMatchingOptionValue(node: SyntaxNode, ...options: Option[]): boolean {\n if (!node?.isNamed) return false;\n if (isOption(node)) {\n return options.some((option) => option.equals(node, true));\n }\n if (node.previousNamedSibling && isOption(node.previousNamedSibling)) {\n return options.some(option => option.matchesValue(node));\n }\n return false;\n}\n"
},
{
"path": "src/parsing/read.ts",
"content": "import { SyntaxNode } from 'web-tree-sitter';\nimport { Option, isMatchingOption, findMatchingOptions, findOptionsSet } from './options';\nimport { isOption, isCommandWithName, isString, isTopLevelDefinition, isProgram, isFunctionDefinition, hasParentFunction, findParentWithFallback, isScope, isInvalidVariableName } from '../utils/node-types';\nimport { FishSymbol, ModifierScopeTag, SetModifierToScopeTag } from './symbol';\nimport { LspDocument } from '../document';\nimport { DefinitionScope } from '../utils/definition-scope';\n\nexport const ReadOptions = [\n Option.create('-U', '--universal'),\n Option.create('-f', '--function'),\n Option.create('-l', '--local'),\n Option.create('-g', '--global'),\n Option.create('-u', '--unexport'),\n Option.create('-x', '--export'),\n Option.create('-c', '--command').withValue(),\n Option.create('-s', '--silent'),\n Option.create('-p', '--prompt').withValue(),\n Option.create('-P', '--prompt-str').withValue(),\n Option.create('-R', '--right-prompt').withValue(),\n Option.create('-S', '--shell'),\n Option.create('-d', '--delimiter').withValue(),\n Option.create('-n', '--nchars').withValue(),\n Option.create('-t', '--tokenize'),\n Option.create('-a', '--list').withAliases('--array'),\n Option.create('-z', '--null'),\n Option.create('-L', '--line'),\n Option.create('-h', '--help'),\n];\n\nexport const ReadModifiers = [\n Option.create('-U', '--universal'),\n Option.create('-f', '--function'),\n Option.create('-l', '--local'),\n Option.create('-g', '--global'),\n];\n\n/**\n * checks if a node is the variable name of a read command\n * read -g -x -p 'stuff' foo bar baz\n * ^ ^ ^\n * | | |\n * cursor could be here\n * invalid variable names include:\n * read -\n * ^\n * |\n * this would signify to read from stdin, not a variable\n * read --\n * ^^\n * ||\n * this would signify to stop parsing options\n */\nexport function isReadVariableDefinitionName(node: SyntaxNode) {\n if (!node.parent || !isReadDefinition(node.parent)) return false;\n const { definitionNodes } = findReadChildren(node.parent);\n return !!definitionNodes.find(n => n.equals(node));\n}\n\nexport function isReadDefinition(node: SyntaxNode) {\n return isCommandWithName(node, 'read') && !node.children.some(child => isMatchingOption(child, Option.create('-q', '--query')));\n}\n\nfunction getFallbackModifierScope(document: LspDocument, node: SyntaxNode) {\n const autoloadType = document.getAutoloadType();\n switch (autoloadType) {\n case 'conf.d':\n case 'config':\n case 'functions':\n return isTopLevelDefinition(node) ? 'global' : hasParentFunction(node) ? 'function' : 'inherit';\n case 'completions':\n return isTopLevelDefinition(node) ? 'local' : hasParentFunction(node) ? 'function' : 'local';\n case '':\n return 'local';\n default:\n return 'inherit';\n }\n}\n\n/**\n * Find all the read command's children that are variable names\n * @param node The node to check isCommandWithName(node, 'read')\n * @returns nodes that are variable names and the modifier if seen\n */\nexport function findReadChildren(node: SyntaxNode): { definitionNodes: SyntaxNode[]; modifier: Option | undefined; } {\n let modifier: Option | undefined = undefined;\n const definitionNodes: SyntaxNode[] = [];\n const allFocused: SyntaxNode[] = node.childrenForFieldName('argument')\n .filter((n) => {\n switch (true) {\n case isMatchingOption(n, Option.create('-l', '--local')):\n case isMatchingOption(n, Option.create('-f', '--function')):\n case isMatchingOption(n, Option.create('-g', '--global')):\n case isMatchingOption(n, Option.create('-U', '--universal')):\n modifier = findMatchingOptions(n, ...ReadModifiers);\n return false;\n case isMatchingOption(n, Option.create('-c', '--command')):\n return false;\n case isMatchingOption(n.previousSibling!, Option.create('-d', '--delimiter')):\n case isMatchingOption(n, Option.create('-d', '--delimiter')):\n return false;\n case isMatchingOption(n.previousSibling!, Option.create('-n', '--nchars')):\n case isMatchingOption(n, Option.create('-n', '--nchars')):\n return false;\n case isMatchingOption(n.previousSibling!, Option.create('-p', '--prompt')):\n case isMatchingOption(n, Option.create('-p', '--prompt')):\n return false;\n case isMatchingOption(n.previousSibling!, Option.create('-P', '--prompt-str')):\n case isMatchingOption(n, Option.create('-P', '--prompt-str')):\n return false;\n case isMatchingOption(n.previousSibling!, Option.create('-R', '--right-prompt')):\n case isMatchingOption(n, Option.create('-R', '--right-prompt')):\n return false;\n case isMatchingOption(n, Option.create('-s', '--silent')):\n case isMatchingOption(n, Option.create('-S', '--shell')):\n case isMatchingOption(n, Option.create('-t', '--tokenize')):\n case isMatchingOption(n, Option.create('-u', '--unexport')):\n case isMatchingOption(n, Option.create('-x', '--export')):\n case isMatchingOption(n, Option.create('-a', '--list')):\n case isMatchingOption(n, Option.create('-z', '--null')):\n case isMatchingOption(n, Option.create('-L', '--line')):\n return false;\n default:\n return true;\n }\n });\n\n allFocused.forEach((arg) => {\n if (isOption(arg)) return;\n if (isString(arg)) return;\n if (isInvalidVariableName(arg)) return;\n definitionNodes.push(arg);\n });\n return {\n definitionNodes,\n modifier,\n };\n}\n\n/**\n * NOTE: `set` uses the parent of the command to determine the scope of the variable\n * At a later date, consider which `scopeNode` should be used for both `set` and `read` commands\n */\nfunction findReadParent(node: SyntaxNode, scopeModifier: ModifierScopeTag): SyntaxNode {\n switch (scopeModifier) {\n case 'global':\n return findParentWithFallback(node, (n) => isProgram(n));\n case 'inherit':\n case 'function':\n return findParentWithFallback(node, (n) => isFunctionDefinition(n) || isProgram(n));\n case 'local':\n default:\n return findParentWithFallback(node, (n) => isScope(n));\n }\n}\n\n/**\n * Get all read command variable names as `FishSymbol[]`\n */\nexport function processReadCommand(document: LspDocument, node: SyntaxNode, children: FishSymbol[] = []) {\n const result: FishSymbol[] = [];\n const { definitionNodes, modifier } = findReadChildren(node);\n\n const scopeModifier = modifier ? SetModifierToScopeTag(modifier) : getFallbackModifierScope(document, node);\n const definitionParent = findReadParent(node, scopeModifier);\n const definitionScope = DefinitionScope.create(definitionParent, scopeModifier);\n\n const options = findOptionsSet([node], ReadOptions)?.map(opt => opt.option) || [];\n\n for (const arg of definitionNodes) {\n if (arg.text.startsWith('$')) continue;\n result.push(FishSymbol.create(arg.text, node, arg, 'READ', document, document.uri, node.text, definitionScope, options, children));\n }\n\n return result;\n}\n"
},
{
"path": "src/parsing/reference-comparator.ts",
"content": "import * as Locations from '../utils/locations';\nimport { SyntaxNode } from 'web-tree-sitter';\nimport { FishSymbol } from './symbol';\nimport { LspDocument } from '../document';\nimport { equalRanges, getChildNodes, getRange } from '../utils/tree-sitter';\nimport { isEmittedEventDefinitionName } from './emit';\nimport { findParentCommand, findParentFunction, isArgumentThatCanContainCommandCalls, isCommand, isCommandWithName, isEndStdinCharacter, isFunctionDefinition, isFunctionDefinitionName, isOption, isString, isVariable, isVariableDefinitionName } from '../utils/node-types';\nimport { isMatchingCompletionFlagNodeWithFishSymbol } from './complete';\nimport { isCompletionArgparseFlagWithCommandName } from './argparse';\nimport { isMatchingOption, isMatchingOptionOrOptionValue, Option } from './options';\nimport { isSetVariableDefinitionName } from './set';\nimport { extractCommands } from './nested-strings';\nimport { isAbbrDefinitionName, isMatchingAbbrFunction } from '../diagnostics/node-types';\nimport { isBindFunctionCall } from './bind';\nimport { isAliasDefinitionValue } from './alias';\n\ntype ReferenceContext = {\n symbol: FishSymbol;\n document: LspDocument;\n node: SyntaxNode;\n excludeEqualNode: boolean;\n};\n\ntype ReferenceCheck = (ctx: ReferenceContext) => boolean;\n\n// Early exit conditions - things we can immediately rule out\nconst shouldSkipNode: ReferenceCheck = ({ symbol, document, node, excludeEqualNode }) => {\n if (excludeEqualNode && symbol.equalsNode(node)) return true;\n\n if (excludeEqualNode && document.uri === symbol.uri) {\n if (equalRanges(getRange(symbol.focusedNode), getRange(node))) {\n return true;\n }\n }\n\n if (excludeEqualNode && symbol.isEvent() && symbol.focusedNode.equals(node)) {\n return true;\n }\n\n return false;\n};\n\n// Event-specific reference checking\nconst checkEventReference: ReferenceCheck = ({ symbol, node }) => {\n if (symbol.isEventHook() && symbol.name === node.text && isEmittedEventDefinitionName(node)) {\n return true;\n }\n\n if (symbol.isEmittedEvent() && symbol.name === node.text && !isEmittedEventDefinitionName(node)) {\n return true;\n }\n\n return false;\n};\n\n// Scope validation for local symbols\nconst isInValidScope: ReferenceCheck = ({ symbol, document, node }) => {\n if (symbol.isLocal() && !symbol.isArgparse()) {\n return symbol.scopeContainsNode(node) && symbol.uri === document.uri;\n }\n return true;\n};\n\n// Function name matching\nconst matchesFunctionName: ReferenceCheck = ({ symbol, node }) => {\n if (symbol.isFunction()) {\n if (isArgumentThatCanContainCommandCalls(node)) return true;\n if (symbol.name !== node.text && !isString(node)) {\n return false;\n }\n }\n return true;\n};\n\n// Complete command reference checking\nconst checkCompleteCommandReference: ReferenceCheck = ({ symbol, node }) => {\n const parentNode = node.parent ? findParentCommand(node) : null;\n\n if (parentNode && isCommandWithName(parentNode, 'complete')) {\n return isMatchingCompletionFlagNodeWithFishSymbol(symbol, node);\n }\n\n return false;\n};\n\n// Argparse-specific reference checking\nconst checkArgparseReference: ReferenceCheck = ({ symbol, node }) => {\n if (!symbol.isArgparse()) return false;\n\n const parentName = symbol.parent?.name\n || symbol.scopeNode.firstNamedChild?.text\n || symbol.scopeNode.text;\n\n // Check completion argparse flags\n if (isCompletionArgparseFlagWithCommandName(node, parentName, symbol.argparseFlagName)) {\n return true;\n }\n\n // Check command options\n if (isOption(node) && node.parent && isCommandWithName(node.parent, parentName)) {\n return isMatchingOptionOrOptionValue(node, Option.fromRaw(symbol.argparseFlag));\n }\n\n // Check variable references\n if (symbol.name === node.text && symbol.parent?.scopeContainsNode(node)) {\n return true;\n }\n\n const parentFunction = findParentFunction(node);\n const parentNode = node.parent ? findParentCommand(node) : null;\n\n // Variable definition checks\n if (isVariable(node) || isVariableDefinitionName(node) || isSetVariableDefinitionName(node, false)) {\n return symbol.name === node.text && symbol.scopeContainsNode(node);\n }\n\n // Command checks\n if (parentNode && isCommandWithName(parentNode, 'set', 'read', 'for', 'export', 'argparse')) {\n return !!(\n symbol.name === node.text\n && symbol.scopeContainsNode(node)\n && parentFunction?.equals(symbol.scopeNode)\n );\n }\n\n return false;\n};\n\n// Function-specific reference checking\nconst checkFunctionReference: ReferenceCheck = ({ symbol, node }) => {\n if (!symbol.isFunction()) return false;\n\n const parentNode = node.parent ? findParentCommand(node) : null;\n const prevNode = node.previousNamedSibling;\n\n // Direct command calls\n if (isCommand(node) && node.text === symbol.name) return true;\n\n // Function definitions (global functions only)\n if (isFunctionDefinitionName(node) && symbol.isGlobal()) {\n return symbol.equalsNode(node);\n }\n if (\n parentNode\n && isCommandWithName(parentNode, symbol.name)\n && parentNode.firstNamedChild?.equals(node)\n ) {\n return true;\n }\n\n // Command with name\n if (isCommandWithName(node, symbol.name)) return true;\n\n // function calls that are strings\n if (isArgumentThatCanContainCommandCalls(node)) {\n if (isString(node) || isOption(node)) {\n return extractCommands(node).some(cmd => cmd === symbol.name);\n }\n return node.text === symbol.name;\n }\n\n // Type/functions commands\n if (parentNode && isCommandWithName(parentNode, 'type', 'functions')) {\n const firstChild = parentNode.namedChildren.find(n => !isOption(n));\n return firstChild?.text === symbol.name;\n }\n\n // Wrapped functions\n if (prevNode && isMatchingOption(prevNode, Option.create('-w', '--wraps')) ||\n node.parent && isFunctionDefinition(node.parent) &&\n isMatchingOptionOrOptionValue(node, Option.create('-w', '--wraps'))) {\n return extractCommands(node).some(cmd => cmd === symbol.name);\n }\n\n // Abbreviation functions\n if (parentNode && isCommandWithName(parentNode, 'abbr')) {\n if (prevNode && isMatchingAbbrFunction(node)) {\n return extractCommands(node).some(cmd => cmd === symbol.name);\n }\n\n const namedChild = getChildNodes(parentNode).find(n => isAbbrDefinitionName(n));\n if (namedChild &&\n Locations.Range.isAfter(getRange(namedChild), symbol.selectionRange) &&\n !isOption(node) && node.text === symbol.name) {\n return true;\n }\n }\n\n // Bind commands\n if (parentNode && isCommandWithName(parentNode, 'bind')) {\n if (isOption(node)) return false;\n\n if (isBindFunctionCall(node)) {\n return extractCommands(node).some(cmd => cmd === symbol.name);\n }\n\n if (isString(node) && extractCommands(node).some(cmd => cmd === symbol.name)) {\n return true;\n }\n\n const cmd = parentNode.childrenForFieldName('argument').slice(1)\n .filter(n => !isOption(n) && !isEndStdinCharacter(n))\n .find(n => n.equals(node) && n.text === symbol.name);\n\n if (cmd) return true;\n }\n\n // Alias commands\n if (parentNode && isCommandWithName(parentNode, 'alias')) {\n if (isAliasDefinitionValue(node)) {\n return extractCommands(node).some(cmd => cmd === symbol.name);\n }\n }\n\n if (parentNode && isCommandWithName(parentNode, 'argparse')) {\n if (isOption(node) || isString(node)) {\n return extractCommands(node).some(cmd => cmd === symbol.name);\n }\n }\n\n // Export/set/read/for/argparse commands\n if (parentNode && isCommandWithName(parentNode, 'export', 'set', 'read', 'for', 'argparse')) {\n if (isOption(node) || isString(node)) {\n return extractCommands(node).some(cmd => cmd === symbol.name);\n }\n if (isVariableDefinitionName(node)) return false;\n\n return symbol.name === node.text;\n }\n\n return symbol.name === node.text && symbol.scopeContainsNode(node);\n};\n\n// Variable-specific reference checking\nconst checkVariableReference: ReferenceCheck = ({ symbol, node }) => {\n if (!symbol.isVariable() || node.text !== symbol.name) return false;\n\n // Check if the node is a variaable definition with the same name\n if (isVariable(node) || isVariableDefinitionName(node)) return true;\n\n const parentNode = node.parent ? findParentCommand(node) : null;\n\n // skip the edge case where a function could share a variables name\n // NOTE: `set FOO ...` is a variable definition\n // • `$FOO` will still be counted as a reference\n // • `FOO` will not be counted as a references (`FOO` could be a function)\n if (parentNode && isCommandWithName(parentNode, symbol.name)) {\n return false;\n }\n\n if (parentNode && isCommandWithName(parentNode, 'export', 'set', 'read', 'for', 'argparse')) {\n if (isOption(node)) return false;\n if (isVariableDefinitionName(node)) return symbol.name === node.text;\n }\n\n return symbol.name === node.text && symbol.scopeContainsNode(node);\n};\n\n// Main reference checker that composes all the checks\nconst referenceCheckers: ReferenceCheck[] = [\n checkEventReference,\n checkArgparseReference,\n checkFunctionReference,\n checkVariableReference,\n];\n\n// Main function - refactored to be functional and composable\nexport const isSymbolReference = (\n symbol: FishSymbol,\n document: LspDocument,\n node: SyntaxNode,\n excludeEqualNode = false,\n): boolean => {\n const ctx: ReferenceContext = { symbol, document, node, excludeEqualNode };\n\n // Early exits\n if (shouldSkipNode(ctx)) return false;\n\n // Check event references first (they have special handling)\n if (symbol.isEvent()) {\n return checkEventReference(ctx);\n }\n\n // Validate scope for local symbols\n if (!isInValidScope(ctx)) return false;\n\n // Validate function name matching\n if (symbol.isFunction() && !matchesFunctionName(ctx)) return false;\n\n // Check complete command references\n const parentNode = node.parent ? findParentCommand(node) : null;\n if (parentNode && isCommandWithName(parentNode, 'complete') && !isVariable(node)) {\n return checkCompleteCommandReference(ctx);\n }\n\n // Run through all specific type checkers\n for (const checker of referenceCheckers) {\n if (checker(ctx)) return true;\n }\n\n return false;\n};\n"
},
{
"path": "src/parsing/set.ts",
"content": "import { SyntaxNode } from 'web-tree-sitter';\nimport { isOption, isCommandWithName, isTopLevelDefinition, findParentCommand, isConditionalCommand, hasParentFunction, findParentWithFallback, isFunctionDefinition, isScope } from '../utils/node-types';\nimport { Option, findOptions, findOptionsSet, isMatchingOption } from './options';\nimport { LspDocument } from '../document';\nimport { FishSymbol, ModifierScopeTag, SetModifierToScopeTag } from './symbol';\nimport { DefinitionScope, ScopeTag } from '../utils/definition-scope';\n\nexport const SetOptions = [\n Option.create('-U', '--universal'),\n Option.create('-g', '--global'),\n Option.create('-f', '--function'),\n Option.create('-l', '--local'),\n Option.create('-x', '--export'),\n Option.create('-u', '--unexport'),\n Option.long('--path'),\n Option.long('--unpath'),\n Option.create('-a', '--append'),\n Option.create('-p', '--prepend'),\n Option.create('-e', '--erase'),\n Option.create('-q', '--query'),\n Option.create('-n', '--names'),\n Option.create('-S', '--show'),\n Option.long('--no-event'),\n Option.create('-L', '--long'),\n Option.create('-h', '--help'),\n];\n\n// const setModifiers = SetOptions.filter(option => option.equalsRawLongOption('--universal', '--global', '--function', '--local'));\nexport const SetModifiers = [\n Option.create('-U', '--universal'),\n Option.create('-g', '--global'),\n Option.create('-f', '--function'),\n Option.create('-l', '--local'),\n];\n\nexport function isSetDefinition(node: SyntaxNode) {\n return isCommandWithName(node, 'set') && !node.children.some(child => isMatchingOption(child, Option.create('-q', '--query'), Option.create('-n', '--names'), Option.create('-S', '--show'), Option.create('-e', '--erase')));\n}\n\nexport function isSetQueryDefinition(node: SyntaxNode) {\n return isCommandWithName(node, 'set') && node.children.some(child => isMatchingOption(child, Option.create('-q', '--query')));\n}\n\n/**\n * checks if a node is the variable name of a set command\n * set -g -x foo '...'\n * ^-- cursor is here\n */\nexport function isSetVariableDefinitionName(node: SyntaxNode, excludeQuery = true) {\n if (!node.parent || !isSetDefinition(node.parent)) return false;\n if (excludeQuery && isSetQueryDefinition(node.parent)) return false;\n const searchNodes = findSetChildren(node.parent);\n const definitionNode = searchNodes.find(n => !isOption(n));\n return !!definitionNode && definitionNode.equals(node);\n}\n\nfunction getFallbackModifierScope(document: LspDocument, node: SyntaxNode) {\n const autoloadType = document.getAutoloadType();\n switch (autoloadType) {\n case 'conf.d':\n case 'config':\n case 'functions':\n return isTopLevelDefinition(node) ? 'global' : hasParentFunction(node) ? 'function' : 'inherit';\n case 'completions':\n return isTopLevelDefinition(node) ? 'local' : hasParentFunction(node) ? 'function' : 'local';\n case '':\n return 'local';\n default:\n return 'inherit';\n }\n}\n\nexport function findSetChildren(node: SyntaxNode) {\n const children = node.childrenForFieldName('argument');\n const firstNonOption = children.findIndex(child => !isOption(child));\n return children.slice(0, firstNonOption + 1);\n}\n\nexport function setModifierDetailDescriptor(node: SyntaxNode) {\n let children = node.childrenForFieldName('argument');\n if (isSetDefinition(node)) children = findSetChildren(node);\n\n const options = findOptions(children, SetModifiers);\n const exportedOption = options.found.find(o => o.option.equalsRawOption('-x', '--export') || o.option.equalsRawOption('-u', '--unexport'));\n const exportedStr = exportedOption ? exportedOption.option.isOption('-x', '--export') ? 'exported' : 'unexported' : '';\n const modifier = options.found.find(o => o.option.equalsRawOption('-U', '-g', '-f', '-l'));\n if (modifier) {\n switch (true) {\n case modifier.option.isOption('-U', '--universal'):\n return ['universally scoped', exportedStr].filter(Boolean).join('; ');\n case modifier.option.isOption('-g', '--global'):\n return ['globally scoped', exportedStr].filter(Boolean).join('; ');\n case modifier.option.isOption('-f', '--function'):\n return ['function scoped', exportedStr].filter(Boolean).join('; ');\n case modifier.option.isOption('-l', '--local'):\n return ['locally scoped', exportedStr].filter(Boolean).join('; ');\n default:\n return ['', exportedStr].filter(Boolean).join('; ');\n }\n }\n return ['', exportedStr].filter(Boolean).join('; ');\n}\n\nfunction findParentScopeNode(commandNode: SyntaxNode, modifier: ModifierScopeTag): SyntaxNode {\n switch (modifier) {\n case 'universal':\n case 'global':\n case 'function':\n return findParentWithFallback(commandNode, (n) => isFunctionDefinition(n));\n case 'inherit':\n case 'local':\n default:\n return findParentWithFallback(commandNode, (n) => isScope(n));\n }\n}\n\nexport function processSetCommand(document: LspDocument, node: SyntaxNode, children: FishSymbol[] = []) {\n /** skip `set -q/--query` && `set -e/--erase` */\n if (!isSetDefinition(node)) return [];\n // create the searchNodes, which are the nodes after the command name, but before the variable name\n const searchNodes = findSetChildren(node);\n // find the definition node, which should be the last node of the searchNodes\n const definitionNode = searchNodes.find(n => !isOption(n));\n\n const skipText: string[] = ['-', '$', '('];\n if (\n !definitionNode\n || definitionNode.type === 'concatenation' // skip `set -e FOO[1]`\n || skipText.some(t => definitionNode.text.startsWith(t)) // skip `set $FOO`, `set (FOO)`, `set -`\n ) return [];\n\n const modifierOption = findOptionsSet(searchNodes, SetModifiers).pop();\n let modifier = 'local' as ScopeTag;\n if (modifierOption) {\n modifier = SetModifierToScopeTag(modifierOption.option) as ScopeTag;\n } else {\n modifier = getFallbackModifierScope(document, node) as ScopeTag;\n }\n\n const options = findOptionsSet(searchNodes, SetOptions).map(o => o.option);\n\n const scopeNode = findParentScopeNode(node, modifier);\n\n // fix conditional_command scoping to use the parent command\n // of the conditional_execution statement, so that\n // we can reference the variable in the parent scope\n let parentNode = findParentCommand(node.parent || node) || node.parent || node;\n if (parentNode && isConditionalCommand(parentNode)) {\n while (parentNode && isConditionalCommand(parentNode)) {\n if (parentNode.type === 'function_definition') break;\n if (!parentNode.parent) break;\n parentNode = parentNode.parent;\n }\n }\n\n return [\n FishSymbol.create(\n definitionNode.text.toString(),\n node,\n definitionNode,\n 'SET',\n document,\n document.uri,\n node.text.toString(),\n DefinitionScope.create(scopeNode, modifier),\n options,\n children,\n ),\n ];\n}\n"
},
{
"path": "src/parsing/source.ts",
"content": "import { SyntaxNode } from 'web-tree-sitter';\nimport { findParentFunction, isCommandWithName, isFunctionDefinition, isProgram, isTopLevelDefinition } from '../utils/node-types';\nimport { SyncFileHelper } from '../utils/file-operations';\nimport { Range } from 'vscode-languageserver';\nimport { LspDocument } from '../document';\nimport { Analyzer } from '../analyze';\nimport { getParentNodesGen, getRange, precedesRange } from '../utils/tree-sitter';\nimport { DefinitionScope } from '../utils/definition-scope';\nimport { FishSymbol } from './symbol';\nimport { uriToPath } from '../utils/translation';\nimport path, { dirname, isAbsolute } from 'path';\nimport { workspaceManager } from '../utils/workspace-manager';\nimport { findFirstExistingFile, isExistingFile } from '../utils/path-resolution';\n\n// TODO think of better naming conventions for these functions\n\nexport function isSourceCommandName(node: SyntaxNode) {\n return isCommandWithName(node, 'source') || isCommandWithName(node, '.');\n}\n\nexport function isSourceCommandWithArgument(node: SyntaxNode) {\n return isSourceCommandName(node) && node.childCount > 1 && node.child(1)?.text !== '-';\n}\n\nexport function isSourceCommandArgumentName(node: SyntaxNode) {\n if (node.parent && isSourceCommandWithArgument(node.parent)) {\n return node.parent?.child(1)?.equals(node) && node.isNamed && node.text !== '-';\n }\n return false;\n}\n\nexport function isSourcedFilename(node: SyntaxNode) {\n if (node.parent && isSourceCommandName(node.parent)) {\n return node.parent?.child(1)?.equals(node) && node.isNamed && node.text !== '-';\n }\n return false;\n}\n\nexport function isExistingSourceFilenameNode(node: SyntaxNode, baseDir?: string) {\n if (!isSourcedFilename(node)) return false;\n const resolvedPath = resolveSourcePath(node.text, baseDir);\n return resolvedPath && isExistingFile(resolvedPath);\n}\n\nexport function getExpandedSourcedFilenameNode(node: SyntaxNode, baseDir?: string) {\n if (!isSourcedFilename(node)) return undefined;\n\n const resolvedPath = resolveSourcePath(node.text, baseDir);\n if (resolvedPath && isExistingFile(resolvedPath)) {\n return SyncFileHelper.expandEnvVars(resolvedPath);\n }\n return undefined;\n}\n\n/**\n * Resolves a source path that might be relative, relative to the base directory\n * @param sourcePath The path from the source command (e.g., \"./scripts/file.fish\", \"/abs/path.fish\")\n * @param baseDir The directory to resolve relative paths against (usually the directory containing the sourcing script)\n * @returns The resolved absolute path, or the original path if it was already absolute\n */\nfunction resolveSourcePath(sourcePath: string, baseDir?: string): string {\n // Expand environment variables first\n const expandedPath = SyncFileHelper.expandEnvVars(sourcePath);\n\n // If it's already an absolute path, return as-is\n if (isAbsolute(expandedPath)) {\n return expandedPath;\n }\n\n // Try to find the file in multiple possible locations\n const foundPath = findFirstExistingFile(\n path.join(baseDir || workspaceManager.current?.path || process.cwd(), expandedPath),\n path.resolve(process.cwd(), expandedPath),\n path.resolve(process.env.PWD || '', expandedPath),\n path.resolve(workspaceManager.current?.path || '', expandedPath),\n );\n\n // Return the found path or the expanded path as fallback\n return foundPath ?? expandedPath;\n}\n\nexport interface SourceResource {\n from: LspDocument;\n to: LspDocument;\n range: Range;\n node: SyntaxNode;\n definitionScope: DefinitionScope;\n // children: FishSymbol[];\n sources: SourceResource[];\n}\n\nexport class SourceResource {\n constructor(\n public from: LspDocument,\n public to: LspDocument,\n public range: Range,\n public node: SyntaxNode,\n public definitionScope: DefinitionScope,\n // public children: FishSymbol[],\n public sources: SourceResource[],\n ) { }\n\n static create(\n from: LspDocument,\n to: LspDocument,\n range: Range,\n node: SyntaxNode,\n sources: SourceResource[],\n ) {\n let scopeParent: SyntaxNode | null = node.parent;\n for (const parent of getParentNodesGen(node)) {\n if (isFunctionDefinition(parent) || isProgram(parent)) {\n scopeParent = parent;\n break;\n }\n }\n const definitionScope = DefinitionScope.create(scopeParent!, 'local');\n return new SourceResource(from, to, range, node, definitionScope, sources);\n }\n\n scopeReachableFromNode(node: SyntaxNode) {\n const parent = findParentFunction(node);\n const isTopLevel = isTopLevelDefinition(this.node);\n if (parent && !isTopLevel) return this.definitionScope.containsNode(node);\n return this.definitionScope.containsNode(node) && node.startIndex >= this.definitionScope.scopeNode.startIndex;\n }\n}\n\nexport function createSourceResources(analyzer: Analyzer, from: LspDocument): SourceResource[] {\n const result: SourceResource[] = [];\n\n // Get the directory containing the current document for resolving relative paths\n const fromPath = uriToPath(from.uri);\n const baseDir = dirname(fromPath);\n\n const nodes = analyzer.getNodes(from.uri).filter(n => {\n return isSourceCommandArgumentName(n) && !!isExistingSourceFilenameNode(n, baseDir);\n });\n if (nodes.length === 0) return result;\n for (const node of nodes) {\n const sourcedFile = getExpandedSourcedFilenameNode(node, baseDir);\n if (!sourcedFile) continue;\n const to = analyzer.getDocumentFromPath(sourcedFile) ||\n SyncFileHelper.toLspDocument(sourcedFile);\n const range = getRange(node);\n analyzer.analyze(to);\n const sources = createSourceResources(analyzer, to);\n result.push(SourceResource.create(from, to, range, node, sources));\n }\n return result;\n}\n\nexport function reachableSources(resources: SourceResource[], uniqueUris: Set = new Set()): SourceResource[] {\n const result: SourceResource[] = [];\n const sourceShouldInclude = (\n child: SourceResource,\n parent: SourceResource,\n ) => {\n return child.definitionScope.containsNode(parent.node)\n && precedesRange(parent.range, child.range)\n && !uniqueUris.has(child.to.uri);\n };\n for (const resource of resources) {\n const children = reachableSources(resource.sources);\n if (!uniqueUris.has(resource.to.uri)) {\n uniqueUris.add(resource.to.uri);\n result.push(resource);\n }\n for (const child of children) {\n if (sourceShouldInclude(child, resource)) {\n uniqueUris.add(child.to.uri);\n result.push(child);\n }\n }\n }\n return result;\n}\n\nexport function symbolsFromResource(analyzer: Analyzer, resources: SourceResource, uniqueNames: Set = new Set()): FishSymbol[] {\n const result: FishSymbol[] = [];\n const symbols = analyzer.getFlatDocumentSymbols(resources.to.uri);\n for (const symbol of symbols) {\n if (uniqueNames.has(symbol.name)) continue;\n if (symbol.isGlobal() || symbol.isRootLevel()) {\n result.push(symbol);\n }\n }\n return result;\n}\n"
},
{
"path": "src/parsing/string.ts",
"content": "import { SyntaxNode } from 'web-tree-sitter';\n\n/**\n * Resolves a single fish shell escape sequence token to its character value.\n *\n * In unquoted fish strings `\\X` where X is not a recognised special character\n * resolves to just `X`. Recognised specials follow the standard C/fish\n * convention (`\\n`, `\\t`, `\\e`, `\\u`, …).\n *\n * @param seq - raw escape-sequence text, e.g. `\\n`, `\\m`, `\\uXXXX`\n * @returns the resolved character(s)\n */\nfunction unescapeSequence(seq: string): string {\n if (!seq.startsWith('\\\\') || seq.length < 2) return seq;\n const char = seq[1]!;\n switch (char) {\n case 'a': return '\\x07'; // bell\n case 'b': return '\\x08'; // backspace\n case 'e': return '\\x1B'; // escape\n case 'f': return '\\x0C'; // form feed\n case 'n': return '\\n'; // newline\n case 'r': return '\\r'; // carriage return\n case 't': return '\\t'; // tab\n case 'v': return '\\x0B'; // vertical tab\n case '\\\\': return '\\\\';\n case ' ': return ' ';\n case 'u': {\n const cp = parseInt(seq.slice(2), 16);\n return isNaN(cp) ? seq : String.fromCodePoint(cp);\n }\n case 'U': {\n const cp = parseInt(seq.slice(2), 16);\n return isNaN(cp) ? seq : String.fromCodePoint(cp);\n }\n case 'x': {\n const cp = parseInt(seq.slice(2), 16);\n return isNaN(cp) ? seq : String.fromCodePoint(cp);\n }\n case 'o': {\n const cp = parseInt(seq.slice(2), 8);\n return isNaN(cp) ? seq : String.fromCodePoint(cp);\n }\n case 'c': {\n const ctrl = seq[2];\n return ctrl ? String.fromCharCode(ctrl.toUpperCase().charCodeAt(0) - 64) : seq;\n }\n default:\n // Any other \\X → X (backslash is simply dropped)\n return char;\n }\n}\n\n/**\n * Utilities for extracting the bare string value from any fish shell string\n * surface form — quoted, escaped, or plain.\n *\n * Fish strings can appear in multiple forms that all denote the same value:\n *\n * `mas` → `word` node / plain text → `\"mas\"`\n * `'mas'` → `single_quote_string` node → `\"mas\"`\n * `\"mas\"` → `double_quote_string` node → `\"mas\"`\n * `\\mas` → `concatenation` node → `\"mas\"`\n * `\\ma\\s` → `concatenation` node → `\"mas\"`\n * `ma\\s` → `concatenation` node → `\"mas\"`\n *\n * @see https://github.com/ndonfris/fish-lsp/issues/140\n */\nexport namespace FishString {\n /**\n * Extracts the bare string value from a fish shell SyntaxNode.\n * Strips surrounding quotes and resolves escape sequences.\n */\n export function fromNode(node: SyntaxNode): string {\n switch (node.type) {\n case 'single_quote_string':\n case 'double_quote_string':\n return node.text.slice(1, -1);\n case 'concatenation':\n return node.children\n .map(child =>\n child.type === 'escape_sequence'\n ? unescapeSequence(child.text)\n : child.text)\n .join('');\n default:\n // Covers plain `word` nodes and any future node types.\n return node.text;\n }\n }\n\n /**\n * Extracts the bare string value from a raw fish shell text string.\n * Strips surrounding quotes and resolves escape sequences.\n * Use `fromNode` instead when a SyntaxNode is available.\n */\n export function fromText(text: string): string {\n if (text.length >= 2) {\n if (text.startsWith(\"'\") && text.endsWith(\"'\")) return text.slice(1, -1);\n if (text.startsWith('\"') && text.endsWith('\"')) return text.slice(1, -1);\n }\n // Resolve escape sequences in unquoted / concatenation-style text.\n // Alternation is ordered longest-first so \\uXXXX is matched before the\n // catch-all single-character branch.\n return text.replace(\n /\\\\(u[0-9a-fA-F]{1,4}|U[0-9a-fA-F]{1,8}|x[0-9a-fA-F]{1,2}|o[0-7]{1,3}|c[a-zA-Z]|[\\s\\S])/g,\n (seq) => unescapeSequence(seq),\n );\n }\n\n /**\n * Convenience overload — dispatches to `fromNode` or `fromText` based on\n * the type of `input`.\n */\n export function parse(input: SyntaxNode | string): string {\n return typeof input === 'string' ? fromText(input) : fromNode(input);\n }\n}\n"
},
{
"path": "src/parsing/symbol-converters.ts",
"content": "import { DocumentSymbol, WorkspaceSymbol, Location, FoldingRange, FoldingRangeKind, MarkupContent, MarkupKind, Hover, DocumentUri } from 'vscode-languageserver';\nimport { FishSymbol } from './symbol';\n\n// === INTERNAL HELPER FUNCTIONS (not exported) ===\nexport namespace SymbolConverters {\n // Internal helper to check if symbol should be included as document symbol\n const shouldIncludeAsDocumentSymbol = (symbol: FishSymbol): boolean => {\n switch (true) {\n case symbol.fishKind === 'FUNCTION_EVENT':\n return false; // Emitted events are not included as document symbols\n default:\n return true;\n }\n };\n\n // Internal helper to process children for document symbols\n const processDocumentSymbolChildren = (symbol: FishSymbol): DocumentSymbol[] => {\n const visitedChildren: DocumentSymbol[] = [];\n\n for (const child of symbol.children) {\n if (!shouldIncludeAsDocumentSymbol(child)) continue;\n\n const newChild = symbolToDocumentSymbol(child);\n if (newChild) {\n visitedChildren.push(newChild);\n }\n }\n\n return visitedChildren;\n };\n\n // Internal helper to create markup content\n const createMarkupContent = (symbol: FishSymbol): MarkupContent => {\n return {\n kind: MarkupKind.Markdown,\n value: symbol.detail,\n };\n };\n\n // === PUBLIC API FUNCTIONS (exported) ===\n\n // Convert symbol to WorkspaceSymbol\n export const symbolToWorkspaceSymbol = (symbol: FishSymbol): WorkspaceSymbol => {\n return WorkspaceSymbol.create(\n symbol.name,\n symbol.kind,\n symbol.uri,\n symbol.selectionRange,\n );\n };\n\n // Convert symbol to DocumentSymbol\n export const symbolToDocumentSymbol = (symbol: FishSymbol): DocumentSymbol | undefined => {\n if (!shouldIncludeAsDocumentSymbol(symbol)) {\n return undefined;\n }\n\n const children = processDocumentSymbolChildren(symbol);\n\n return DocumentSymbol.create(\n symbol.name,\n symbol.detail,\n symbol.kind,\n symbol.range,\n symbol.selectionRange,\n children,\n );\n };\n\n // Convert symbol to Location\n export const symbolToLocation = (symbol: FishSymbol): Location => {\n return Location.create(\n symbol.uri,\n symbol.selectionRange,\n );\n };\n\n // Convert symbol to Position\n export const symbolToPosition = (symbol: FishSymbol): { line: number; character: number; } => {\n return {\n line: symbol.selectionRange.start.line,\n character: symbol.selectionRange.start.character,\n };\n };\n\n // Convert symbol to FoldingRange\n export const symbolToFoldingRange = (symbol: FishSymbol): FoldingRange => {\n return {\n startLine: symbol.range.start.line,\n endLine: symbol.range.end.line,\n startCharacter: symbol.range.start.character,\n endCharacter: symbol.range.end.character,\n collapsedText: symbol.name,\n kind: FoldingRangeKind.Region,\n };\n };\n\n // Convert symbol to MarkupContent\n export const symbolToMarkupContent = (symbol: FishSymbol): MarkupContent => {\n return createMarkupContent(symbol);\n };\n\n // Convert symbol to Hover (with optional current URI for range inclusion)\n export const symbolToHover = (symbol: FishSymbol, currentUri: DocumentUri = ''): Hover => {\n return {\n contents: createMarkupContent(symbol),\n range: currentUri === symbol.uri ? symbol.selectionRange : undefined,\n };\n };\n\n export const copySymbol = (symbol: FishSymbol): FishSymbol => {\n return new FishSymbol({\n name: symbol.name,\n detail: symbol.detail,\n document: symbol.document,\n uri: symbol.uri,\n fishKind: symbol.fishKind,\n node: symbol.node,\n focusedNode: symbol.focusedNode,\n scope: symbol.scope,\n range: symbol.range,\n selectionRange: symbol.selectionRange,\n children: symbol.children.map(copySymbol), // NOT Recursive but probably should be\n });\n };\n\n export const symbolToString = (symbol: FishSymbol): string => {\n return JSON.stringify({\n name: symbol.name,\n kind: symbol.kind,\n uri: symbol.uri,\n scope: symbol.scope.scopeTag,\n detail: symbol.detail,\n range: symbol.range,\n selectionRange: symbol.selectionRange,\n aliasedNames: symbol.aliasedNames,\n children: symbol.children.map(child => child.name),\n }, null, 2);\n };\n\n}\n"
},
{
"path": "src/parsing/symbol-detail.ts",
"content": "import { SymbolKind } from 'vscode-languageserver';\nimport { FishSymbol, fishSymbolKindToSymbolKind } from './symbol';\nimport { md } from '../utils/markdown-builder';\nimport { findOptions } from './options';\nimport { findFunctionDefinitionChildren, FunctionOptions } from './function';\nimport { uriToReadablePath, uriToPath } from '../utils/translation';\nimport { FishString } from './string';\nimport { PrebuiltDocumentationMap } from '../utils/snippets';\nimport { setModifierDetailDescriptor, SetModifiers } from './set';\nimport { SyntaxNode } from 'web-tree-sitter';\nimport { FishAlias } from './alias';\nimport { env } from '../utils/env-manager';\nimport { logger } from '../logger';\n\n// IF YOU ARE READING THIS FILE, PLEASE FEEL FREE TO REFACTOR IT (sorry my brain is fried)\n\n/**\n * Since a SyntaxNode's text could equal something like:\n * ```fish\n * # assume we are indented one level, (if_statement wont have leading spaces)\n * if true\n * echo \"Hello, world!\"\n * end\n * ```\n * We want to remove a single indentation level from the text, after the first line.\n * @param node The SyntaxNode to unindent\n * @returns The unindented text of the SyntaxNode (the last line's indentation amount will be how much is removed from the rest of the lines)\n */\nexport function unindentNestedSyntaxNode(node: SyntaxNode) {\n const lines = node.text.split('\\n');\n if (lines.length > 1) {\n const lastLine = node.lastChild?.startPosition.column || 0;\n return lines\n .map(line => line.replace(' '.repeat(lastLine), ''))\n .join('\\n')\n .trimEnd();\n }\n return node.text;\n}\n\nfunction getSymbolKind(symbol: FishSymbol) {\n const kind = fishSymbolKindToSymbolKind[symbol.fishKind];\n switch (kind) {\n case SymbolKind.Variable:\n return 'variable';\n case SymbolKind.Function:\n return 'function';\n default:\n return '';\n }\n}\n\n/**\n * Checks if a file path is within any autoloaded fish directories\n *\n * @param uriOrPath The URI or filesystem path to check\n * @param type Optional specific autoload type to check for (e.g., 'functions', 'completions')\n * @returns True if the path is within an autoloaded directory, false otherwise\n */\nexport function isAutoloadedPath(uriOrPath: string, type?: string): boolean {\n // Convert URI to path if necessary\n const path = uriOrPath.startsWith('file://') ? uriToPath(uriOrPath) : uriOrPath;\n\n // Get all autoloaded variables from the environment\n const autoloadedKeys = env.getAutoloadedKeys();\n\n for (const key of autoloadedKeys) {\n // Skip if we're looking for a specific type and this key doesn't match\n if (type && !key.toLowerCase().includes(type.toLowerCase())) {\n continue;\n }\n\n const values = env.getAsArray(key);\n\n for (const value of values) {\n if (path.startsWith(value)) {\n return true;\n }\n }\n }\n\n return false;\n}\n\n/**\n * Gets the autoload type of a path if it is autoloaded\n *\n * @param uriOrPath The URI or filesystem path to check\n * @returns The identified autoload type ('functions', 'completions', 'conf.d', etc.) or empty string if not autoloaded\n */\nexport function getAutoloadType(uriOrPath: string): string {\n // Convert URI to path if necessary\n const path = uriOrPath.startsWith('file://') ? uriToPath(uriOrPath) : uriOrPath;\n\n // Common autoload types to check for\n const autoloadTypes = ['functions', 'completions', 'conf.d', 'config'];\n\n // Check path for these common types\n for (const type of autoloadTypes) {\n if (path.includes(`/fish/${type}`)) {\n return type;\n }\n\n // Special case for config.fish\n if (type === 'config' && path.endsWith('config.fish')) {\n return 'config';\n }\n }\n\n // If no specific type was found but the path is autoloaded, return a generic indicator\n if (isAutoloadedPath(path)) {\n return 'autoloaded';\n }\n\n return '';\n}\n\nfunction buildFunctionDetail(symbol: FishSymbol) {\n const { name, node, fishKind } = symbol;\n if (fishKind === 'ALIAS') {\n return FishAlias.buildDetail(node) as string;\n }\n\n const options = findOptions(findFunctionDefinitionChildren(node), FunctionOptions);\n const descriptionOption = options.found.find(option => option.option.isOption('-d', '---description'));\n const description = [`(${md.bold('function')}) ${md.inlineCode(name)}`];\n if (descriptionOption && descriptionOption.value) {\n description.push(\n FishString.fromNode(descriptionOption.value),\n );\n }\n\n description.push(md.separator());\n const scope: string[] = [];\n if (isAutoloadedPath(symbol.uri)) {\n scope.push('autoloaded');\n }\n if (symbol.isGlobal()) {\n scope.push('globally scoped');\n }\n if (scope.length > 0) {\n description.push(scope.join(', '));\n }\n\n description.push(`located in file: ${md.inlineCode(uriToReadablePath(symbol.uri))}`);\n description.push(md.separator());\n const prebuilt = PrebuiltDocumentationMap.getByType('command').find(c => c.name === name);\n if (prebuilt) {\n description.push(prebuilt.description);\n description.push(md.separator());\n }\n\n description.push(md.codeBlock('fish', unindentNestedSyntaxNode(node)));\n\n const argumentNamesOption = options.found.filter(option => option.option.isOption('-a', '--argument-names'));\n if (argumentNamesOption && argumentNamesOption.length) {\n const functionCall = [name];\n for (const arg of argumentNamesOption) {\n functionCall.push(arg.value.text);\n }\n description.push(md.separator());\n description.push(md.codeBlock('fish', functionCall.join(' ')));\n }\n return description.join(md.newline());\n}\n\nfunction isVariableArgumentNamed(node: SyntaxNode, name: string) {\n if (node.type !== 'function_definition') return '';\n const children = findFunctionDefinitionChildren(node);\n if (findOptions(children, FunctionOptions).found\n .filter(flag => flag.option.isOption('-a', '--argument-names'))\n .some(flag => flag.value.text === name)) {\n return true;\n }\n return false;\n}\n\nfunction getArgumentNamesIndexString(node: SyntaxNode, name: string) {\n if (node?.type && node?.type !== 'function_definition') return '';\n const children = findFunctionDefinitionChildren(node);\n // const resultFlags: string[] = [];\n const index = findOptions(children, FunctionOptions).found\n .filter(flag => flag.option.isOption('-a', '--argument-names'))\n .findIndex((flag) => flag.value.text === name);\n const argvStr = '$argv[' + (index + 1) + ']';\n return `${md.italic('named argument')}: ${md.inlineCode(argvStr)}`;\n}\n\nfunction buildVariableDetail(symbol: FishSymbol) {\n const { name, node, uri, fishKind } = symbol;\n if (!node) return '';\n const description = [`(${md.bold('variable')}) ${md.inlineCode(name)}`];\n // add short info about variable\n description.push(md.separator());\n if (fishKind === 'SET' || fishKind === 'READ') {\n const setModifiers = SetModifiers.filter(option => option.equalsRawLongOption('--universal', '--global', '--function', '--local', '--export', '--unexport'));\n const options = findOptions(node.childrenForFieldName('argument'), setModifiers);\n const modifier = options.found.find(o => o.option.equalsRawOption('-U', '-g', '-f', '-l', '-x', '-u'));\n if (modifier) {\n description.push(setModifierDetailDescriptor(node));\n }\n } else if (fishKind === 'ARGPARSE') {\n description.push('locally scoped');\n } else if (node && isVariableArgumentNamed(node, name)) {\n try {\n const result = getArgumentNamesIndexString(node, name);\n description.push(result);\n } catch (e) {\n logger.error('ERROR: building variable detail', e);\n }\n }\n // add location\n description.push(`located in file: ${md.inlineCode(uriToReadablePath(uri))}`);\n // add prebuilt documentation if available\n const prebuilt = PrebuiltDocumentationMap.getByType('variable').find(c => c.name === name);\n if (prebuilt) {\n description.push(md.separator());\n description.push(prebuilt.description);\n }\n description.push(md.separator());\n // add code block of entire region\n description.push(md.codeBlock('fish', unindentNestedSyntaxNode(node)));\n // add trailing `cmd --arg`, `cmd $argv`, `func $argv` examples\n const scopeCommand = symbol.scope.scopeNode?.type === 'program'\n ? `${uriToReadablePath(uri)}`\n : `${symbol.scope.scopeNode?.firstNamedChild?.text}` || `${symbol.node}`;\n if (fishKind === 'ARGPARSE') {\n const argumentNamesOption = symbol.name.slice('_flag_'.length).replace(/_/g, '-');\n if (argumentNamesOption.length > 1) {\n description.push(md.separator());\n description.push(md.codeBlock('fish', `${scopeCommand} --${argumentNamesOption}`));\n } else if (argumentNamesOption.length === 1) {\n description.push(md.separator());\n description.push(md.codeBlock('fish', `${scopeCommand} -${argumentNamesOption}`));\n }\n } else if (name === 'argv') {\n description.push(md.separator());\n description.push(md.codeBlock('fish', `${scopeCommand} $argv`));\n } else if (node.type === 'function_definition') {\n const children = findFunctionDefinitionChildren(node);\n const resultFlags: string[] = [];\n findOptions(children, FunctionOptions).found\n .filter(flag => flag.option.isOption('-a', '--argument-names'))\n .forEach((flag, idx) => {\n if (flag.value.text === name) resultFlags.push(flag.value.text);\n else resultFlags.push(`\\$argv[${idx + 1}]`);\n });\n\n if (resultFlags.length) {\n description.push(md.separator());\n description.push(md.codeBlock('fish', `${scopeCommand} ${resultFlags.join(' ')}`));\n }\n }\n\n return description.join(md.newline());\n}\n\nexport function createDetail(symbol: FishSymbol) {\n if (symbol.fishKind === 'EXPORT') return symbol.detail.toString();\n\n const symbolKind = getSymbolKind(symbol);\n if (symbolKind === '') return symbol.detail;\n\n if (symbolKind === 'function') {\n return buildFunctionDetail(symbol);\n }\n\n if (symbolKind === 'variable') {\n return buildVariableDetail(symbol);\n }\n return symbol.detail.toString();\n}\n"
},
{
"path": "src/parsing/symbol-kinds.ts",
"content": "import { SymbolKind, Range } from 'vscode-languageserver';\nimport { FishSymbol } from './symbol';\nimport { Option } from './options';\n\n/**\n * ALL possible `FishSymbol.fishKind` values\n */\nexport type FishSymbolKind = 'ARGPARSE' | 'FUNCTION' | 'ALIAS' | 'COMPLETE' | 'SET' | 'READ' | 'FOR' | 'VARIABLE' | 'FUNCTION_VARIABLE' | 'EXPORT' | 'EVENT' | 'FUNCTION_EVENT' | 'INLINE_VARIABLE';\n\n/**\n * Map/Record of all possible FishSymbolKind values, with lowercase keys to uppercase values.\n * Uppercase values are used for the `FishSymbol.fishKind` property.\n * Lowercase keys are used for displaying the fishKind in the UI.\n */\nexport const FishSymbolKindMap: Record, FishSymbolKind> = {\n ['argparse']: 'ARGPARSE',\n ['function']: 'FUNCTION',\n ['alias']: 'ALIAS',\n ['complete']: 'COMPLETE',\n ['set']: 'SET',\n ['read']: 'READ',\n ['for']: 'FOR',\n ['variable']: 'VARIABLE',\n ['event']: 'EVENT',\n ['function_variable']: 'FUNCTION_VARIABLE',\n ['function_event']: 'FUNCTION_EVENT',\n ['export']: 'EXPORT',\n ['inline_variable']: 'INLINE_VARIABLE',\n};\n\n/**\n * Maps FishSymbolKind to SymbolKind for use in the LSP.\n * Each FishSymbol.fishKind is mapped to its corresponding SymbolKind.\n */\nexport const fishSymbolKindToSymbolKind: Record = {\n ['ARGPARSE']: SymbolKind.Variable,\n ['FUNCTION']: SymbolKind.Function,\n ['ALIAS']: SymbolKind.Function,\n ['COMPLETE']: SymbolKind.Interface,\n ['SET']: SymbolKind.Variable,\n ['READ']: SymbolKind.Variable,\n ['FOR']: SymbolKind.Variable,\n ['VARIABLE']: SymbolKind.Variable,\n ['FUNCTION_VARIABLE']: SymbolKind.Variable,\n ['EVENT']: SymbolKind.Event,\n ['FUNCTION_EVENT']: SymbolKind.Event,\n ['EXPORT']: SymbolKind.Variable,\n ['INLINE_VARIABLE']: SymbolKind.Variable,\n} as const;\n\n/**\n * Creates an object that returns the string representation of each SymbolKind.\n */\nexport const createSymbolKindLookup = (): Record => {\n const lookup = {} as Record;\n for (const [key, value] of Object.entries(SymbolKind)) {\n if (typeof value === 'number') {\n lookup[value] = key;\n }\n }\n return lookup;\n};\n\nconst symbolKindToStringMap = createSymbolKindLookup();\n/**\n * Function to get the string representation of a SymbolKind, from its numeric value.\n */\nexport const getSymbolKindToString = (kind: SymbolKind): string => {\n return symbolKindToStringMap[kind] || 'Unknown';\n};\n\nexport namespace FishSymbolKind {\n\n /**\n * Checks if the given kind is a valid FishSymbolKind.\n */\n export const is = (kind: unknown): kind is FishSymbolKind => {\n if (typeof kind !== 'string') return false;\n return Object.keys(FishSymbolKindMap).includes(kind.toLowerCase());\n };\n\n /**\n * Converts a FishSymbolKind to its corresponding SymbolKind string.\n */\n export const toSymbolKindStr = (kind: FishSymbolKind): string => {\n return fishSymbolKindToSymbolKind[kind]?.toString();\n };\n}\n\nexport const fromFishSymbolKindToSymbolKind = (kind: FishSymbolKind) => fishSymbolKindToSymbolKind[kind];\n\n/**\n * Converts either a FishSymbol.fishKind or a SymbolKind to its string representation.\n */\nexport const symbolKindToString = (kind: SymbolKind | FishSymbolKind): string => {\n if (FishSymbolKind.is(kind)) {\n return FishSymbolKind.toSymbolKindStr(kind);\n }\n return getSymbolKindToString(kind);\n};\n\n/***\n * Used to simplify checking FishSymbol.is()\n */\ntype kindGroups = 'VARIABLES' | 'FUNCTIONS' | 'EVENTS' | 'ARGPARSE' | 'OTHER';\nexport const FishKindGroups: Record = {\n VARIABLES: ['ARGPARSE', 'SET', 'READ', 'FOR', 'VARIABLE', 'FUNCTION_VARIABLE', 'EXPORT'],\n FUNCTIONS: ['FUNCTION', 'ALIAS'],\n EVENTS: ['EVENT', 'FUNCTION_EVENT'],\n ARGPARSE: ['ARGPARSE'],\n OTHER: ['COMPLETE'],\n} as const;\n\n/**\n * FishSymbolInput is a type that represents the input required to create a FishSymbol.\n * These are the minimum required fields to build all of the FishSymbol properties.\n */\nexport type FishSymbolInput = Pick & {\n name?: string;\n uri?: string;\n range?: Range;\n selectionRange?: Range;\n options?: Option[];\n};\n"
},
{
"path": "src/parsing/symbol-modifiers.ts",
"content": "import { SetOptions } from './set';\nimport { ReadOptions } from './read';\nimport { ArgparseOptions } from './argparse';\nimport { CompleteOptions } from './complete';\nimport { FunctionOptions, FunctionVariableOptions } from './function';\nimport { FishSymbolKind } from './symbol-kinds';\nimport { Option } from './options';\nimport { SemanticTokenModifier, SemanticTokenType } from '../utils/semantics';\nimport { FishSymbol } from './symbol';\n\nexport const SymbolModifiers: Record = {\n SET: SetOptions,\n READ: ReadOptions,\n FOR: [],\n ARGPARSE: ArgparseOptions,\n VARIABLE: [],\n FUNCTION_VARIABLE: [...FunctionVariableOptions],\n FUNCTION: FunctionOptions,\n ALIAS: [Option.create('-g', '--global'), Option.create('-f', '--function')],\n COMPLETE: CompleteOptions,\n EVENT: [],\n FUNCTION_EVENT: [],\n EXPORT: [Option.create('-g', '--global'), Option.create('-x', '--export')],\n INLINE_VARIABLE: [Option.create('-x', '--export')],\n};\n\nfunction getSetReadModifiers(symbol: FishSymbol): SemanticTokenModifier[] {\n const options: Option[] = symbol.options || [];\n const result = new Set();\n result.add(symbol.scopeTag as SemanticTokenModifier);\n for (const opt of options) {\n if (opt.isOption('-g', '--global')) {\n result.add('global');\n }\n if (opt.isOption('-l', '--local')) {\n result.add('local');\n }\n if (opt.isOption('-x', '--export')) {\n result.add('export');\n }\n if (opt.isOption('-U', '--universal')) {\n result.add('universal');\n }\n if (opt.isOption('-f', '--function')) {\n result.add('function');\n }\n }\n if (!result.has(symbol.scopeTag)) {\n result.add(symbol.scopeTag as SemanticTokenModifier);\n }\n if (result.size === 0) {\n result.add('local');\n }\n return Array.from([...result]);\n}\n\nexport const scopeTagToModifierMap: Record = {\n global: 'global',\n local: 'local',\n universal: 'universal',\n function: 'function',\n inherit: 'inherit',\n};\n\nexport function getSymbolModifiers(symbol: FishSymbol): SemanticTokenModifier[] {\n // const mods: FishSemanticTokenModifier[] = ['definition'];\n const mods: SemanticTokenModifier[] = [];\n switch (symbol.fishKind) {\n case 'SET':\n case 'READ':\n return [...mods, ...getSetReadModifiers(symbol)];\n case 'FUNCTION':\n if (\n symbol.isGlobal()\n && symbol.document.isAutoloaded()\n && symbol.name === symbol.document.getAutoLoadName()\n ) {\n mods.push('global' /*'autoloaded'*/);\n } else if (symbol.isLocal() && symbol.document.isAutoloadedUri()) {\n mods.push('local' /*'not-autoloaded'*/);\n } else if (symbol.isLocal()) {\n mods.push('local');\n }\n return mods;\n case 'FUNCTION_VARIABLE':\n if (scopeTagToModifierMap[symbol.scope.scopeTag]) {\n return [...mods, scopeTagToModifierMap[symbol.scope.scopeTag]!];\n }\n return mods;\n case 'ARGPARSE':\n return [...mods, 'local'];\n case 'ALIAS':\n if (symbol.document.isAutoloaded() && symbol.scope.scopeTag === 'global') mods.push('global');\n mods.push(/*'script'*/);\n return mods;\n case 'EXPORT':\n return [...mods, 'global', 'export'];\n case 'FOR':\n return [...mods, 'local'];\n case 'VARIABLE':\n if (scopeTagToModifierMap[symbol.scope.scopeTag]) {\n mods.push(scopeTagToModifierMap[symbol.scope.scopeTag]!);\n return mods;\n }\n return [];\n case 'EVENT':\n case 'FUNCTION_EVENT':\n if (symbol.scope.scopeTag) {\n mods.push(scopeTagToModifierMap[symbol.scope.scopeTag] ?? 'local');\n return mods;\n }\n return [];\n case 'COMPLETE':\n if (symbol.scope.scopeTag) {\n mods.push(scopeTagToModifierMap[symbol.scope.scopeTag] ?? 'local');\n return mods;\n }\n return mods;\n default:\n return [];\n }\n}\n\nexport const FishSymbolToSemanticToken: Record = {\n SET: 'variable',\n READ: 'variable',\n FOR: 'variable',\n ARGPARSE: 'variable',\n VARIABLE: 'variable',\n FUNCTION_VARIABLE: 'variable',\n FUNCTION: 'function',\n ALIAS: 'function',\n COMPLETE: 'function',\n EVENT: 'event',\n FUNCTION_EVENT: 'event',\n EXPORT: 'variable',\n INLINE_VARIABLE: 'variable',\n};\n"
},
{
"path": "src/parsing/symbol.ts",
"content": "import { DocumentSymbol, SymbolKind, WorkspaceSymbol, Location, FoldingRange, MarkupContent, Hover, DocumentUri, Position } from 'vscode-languageserver';\nimport { SyntaxNode } from 'web-tree-sitter';\nimport { DefinitionScope } from '../utils/definition-scope';\nimport { LspDocument } from '../document';\nimport { containsNode, getChildNodes, getRange } from '../utils/tree-sitter';\nimport { findSetChildren, processSetCommand } from './set';\nimport { processReadCommand } from './read';\nimport { isFunctionVariableDefinitionName, processArgvDefinition, processFunctionDefinition } from './function';\nimport { processForDefinition } from './for';\nimport { convertNodeRangeWithPrecedingFlag, processArgparseCommand } from './argparse';\nimport { Flag, isMatchingOption, LongFlag, Option, ShortFlag } from './options';\nimport { processAliasCommand } from './alias';\nimport { createDetail } from './symbol-detail';\nimport { config } from '../config';\nimport { flattenNested } from '../utils/flatten';\nimport { uriToPath } from '../utils/translation';\nimport { FishString } from './string';\nimport { isCommand, isCommandWithName, isEmptyString, isFunctionDefinitionName, isVariableDefinitionName } from '../utils/node-types';\nimport { SyncFileHelper } from '../utils/file-operations';\nimport { isExportVariableDefinitionName, processExportCommand } from './export';\nimport { CompletionSymbol, isCompletionCommandDefinition, isCompletionSymbol } from './complete';\nimport { analyzer } from '../analyze';\nimport { isEmittedEventDefinitionName, isGenericFunctionEventHandlerDefinitionName, processEmitEventCommandName } from './emit';\nimport { isSymbolReference } from './reference-comparator';\nimport { equalSymbolDefinitions, equalSymbols, equalSymbolScopes, fishSymbolNameEqualsNodeText, isFishSymbol, symbolContainsNode, symbolContainsPosition, symbolContainsScope, symbolEqualsLocation, symbolEqualsNode, symbolScopeContainsNode } from './equality-utils';\nimport { SymbolConverters } from './symbol-converters';\nimport { FishKindGroups, FishSymbolInput, FishSymbolKind, fishSymbolKindToSymbolKind, fromFishSymbolKindToSymbolKind } from './symbol-kinds';\nimport { isInlineVariableAssignment, processInlineVariables } from './inline-variable';\n\nexport const SKIPPABLE_VARIABLE_REFERENCE_NAMES = [\n 'argv',\n 'fish_trace',\n];\n\nexport interface FishSymbol extends DocumentSymbol {\n document: LspDocument;\n uri: string;\n fishKind: FishSymbolKind;\n node: SyntaxNode;\n focusedNode: SyntaxNode;\n scope: DefinitionScope;\n children: FishSymbol[];\n detail: string;\n options: Option[];\n parent: FishSymbol | undefined;\n}\n\nexport class FishSymbol {\n public children: FishSymbol[] = [];\n public aliasedNames: string[] = [];\n public document: LspDocument;\n public options: Option[] = [];\n\n constructor(obj: FishSymbolInput) {\n this.name = obj.name || obj.focusedNode.text;\n this.kind = fromFishSymbolKindToSymbolKind(obj.fishKind);\n this.fishKind = obj.fishKind;\n this.document = obj.document;\n this.uri = obj.uri || obj.document.uri.toString();\n this.range = obj.range || getRange(obj.node);\n this.selectionRange = obj.selectionRange || getRange(obj.focusedNode);\n this.node = obj.node;\n this.focusedNode = obj.focusedNode;\n this.scope = obj.scope;\n this.children = obj.children;\n this.children.forEach(child => {\n child.parent = this;\n });\n this.options = obj.options || [];\n this.detail = obj.detail;\n this.setupDetail();\n }\n\n setupDetail() {\n this.detail = createDetail(this);\n }\n\n static create(\n name: string,\n node: SyntaxNode,\n focusedNode: SyntaxNode,\n fishKind: FishSymbolKind,\n document: LspDocument,\n uri: string = document.uri.toString(),\n detail: string,\n scope: DefinitionScope,\n options: Option[] = [],\n children: FishSymbol[] = [],\n ) {\n return new this({\n name: name || focusedNode.text,\n fishKind,\n document,\n uri,\n detail,\n node,\n focusedNode,\n options,\n scope,\n children,\n });\n }\n\n static fromObject(obj: FishSymbolInput) {\n return new this(obj);\n }\n\n public copy(): FishSymbol {\n return SymbolConverters.copySymbol(this);\n }\n\n static is(obj: unknown): obj is FishSymbol {\n return isFishSymbol(obj);\n }\n\n addChildren(...children: FishSymbol[]) {\n this.children.push(...children);\n children.forEach(child => {\n child.parent = this;\n });\n return this;\n }\n\n addAliasedNames(...names: string[]) {\n this.aliasedNames.push(...names);\n return this;\n }\n\n private nameEqualsNodeText(node: SyntaxNode) {\n return fishSymbolNameEqualsNodeText(this, node);\n }\n\n public isBefore(other: FishSymbol, urisMustMatch = true) {\n if (this.uri !== other.uri) return !urisMustMatch;\n return this.focusedNode.startIndex < other.focusedNode.startIndex;\n }\n\n public isAfter(other: FishSymbol, urisMustMatch = true) {\n if (this.uri !== other.uri) return !urisMustMatch;\n return this.focusedNode.startIndex > other.focusedNode.startIndex;\n }\n\n /**\n * Returns the `argparse flag-name` for the symbol `_flag_flag_name`\n */\n public get argparseFlagName() {\n return FishSymbol.argparseFlagFromName(this.name);\n }\n\n /**\n * Static method to convert a FishSymbol.isArgparse() with `_flag_variable_name` to `variable-name`\n */\n public static argparseFlagFromName(name: string) {\n return name.replace(/^_flag_/, '').replace(/_/g, '-');\n }\n\n /**\n * Returns the argparse flag for the symbol, e.g. `-f` or `--flag-name`\n */\n public get argparseFlag(): Flag | string {\n if (this.fishKind !== 'ARGPARSE') return this.name;\n const flagName = this.argparseFlagName;\n if (flagName.length === 1) {\n return `-${flagName}` as ShortFlag;\n }\n return `--${flagName}` as LongFlag;\n }\n\n /**\n * Checks if an argparse _flag_name FishSymbol is equal to a SyntaxNode,\n * where the SyntaxNode corresponds to the argparse\n *\n *\n * ```fish\n * function this.parent.name\n * argparse f/flag-name -- $argv\n * # ^^^^^^^^^^^---- This is the argparse flag name\n * end\n *\n * complete -c this.parent.name -s f -l flag-name\n * # ^ ^^^^^^^^^ Either of these could be the node (depending on the FishSymbol selected)\n * ```\n *\n * @param node - The SyntaxNode to check against (`complete ... -s/-l NODE`)\n * @return {boolean} - True if the node matches the argparse flag name, false otherwise\n */\n private isArgparseCompletionFlag(node: SyntaxNode): boolean {\n if (this.fishKind === 'ARGPARSE') return false;\n if (node.parent && isCommandWithName(node, 'complete')) {\n const flagName = this.argparseFlagName;\n if (node.previousSibling) {\n return flagName.length === 1\n ? Option.create('-s', '--short').matches(node.previousSibling)\n : Option.create('-l', '--long').matches(node.previousSibling);\n }\n }\n return false;\n }\n\n /**\n * Checks if the node is a command completion flag, e.g. `complete -c NODE` or `complete --command NODE`\n */\n private isCommandCompletionFlag(node: SyntaxNode) {\n if (this.fishKind === 'COMPLETE') return false;\n if (node.parent && isCommandWithName(node.parent, 'complete')) {\n if (node.previousSibling) {\n return Option.create('-c', '--command').matches(node.previousSibling);\n }\n }\n return false;\n }\n\n isExported(): boolean {\n if (this.fishKind === 'EVENT') return false;\n if (this.fishKind === 'FUNCTION_EVENT') return false;\n if (this.isFunction()) return false;\n if (this.fishKind === 'FUNCTION_VARIABLE') return false;\n if (!this.isVariable()) return false;\n if (this.isArgparse()) return false;\n if (this.fishKind === 'EXPORT') return true;\n const commandNode = this.node;\n if (isCommandWithName(commandNode, 'set')) {\n const children = findSetChildren(commandNode)\n .filter(s => s.startIndex < this.focusedNode.startIndex);\n return children.some(s => isMatchingOption(s, Option.create('-x', '--export')));\n }\n if (isCommandWithName(commandNode, 'read')) {\n const children = commandNode.children\n .filter(s => s.startIndex < this.focusedNode.startIndex);\n return children.some(s => isMatchingOption(s, Option.create('-x', '--export')));\n }\n return false;\n }\n\n isEqualLocation(node: SyntaxNode) {\n if (!node.isNamed || this.focusedNode.equals(node) || !this.nameEqualsNodeText(node)) {\n return false;\n }\n switch (this.fishKind) {\n case 'FUNCTION':\n case 'ALIAS':\n return node.parent && isCommandWithName(node.parent, 'complete')\n ? !isVariableDefinitionName(node) && !isCommand(node) && this.isCommandCompletionFlag(node)\n : !isVariableDefinitionName(node) && !isCommand(node);\n case 'ARGPARSE':\n // return !isFunctionDefinitionName(node) && isMatchingCompleteOptionIsCommand(node);\n return !isFunctionDefinitionName(node) || this.isArgparseCompletionFlag(node);\n case 'SET':\n case 'READ':\n case 'FOR':\n case 'VARIABLE':\n return !isFunctionDefinitionName(node);\n case 'EXPORT':\n return isExportVariableDefinitionName(node);\n case 'FUNCTION_VARIABLE':\n return isFunctionVariableDefinitionName(node);\n case 'EVENT':\n return isEmittedEventDefinitionName(node);\n case 'FUNCTION_EVENT':\n return isGenericFunctionEventHandlerDefinitionName(node);\n case 'COMPLETE':\n return isCompletionCommandDefinition(node) || isCompletionSymbol(node);\n default:\n return false;\n }\n }\n\n /**\n * Determines if the symbol requires local references to be found, which is used\n * to skip matching diagnostics `4004`|`unused symbol` for certain matches.\n *\n * Examples include:\n * - Functions which are autoloaded based on their path and file name.\n * - Variables which are autoloaded based on their path.\n * - Variables which are exported or global do not need local references.\n * - Variables like `argv` and `fish_trace` do not need local references.\n * - Variables like `for i in (seq 1 10); ;end;` do not need local references (iterate 10 times)\n *\n * @return {boolean} True if the symbol needs local references, false otherwise\n */\n needsLocalReferences(): boolean {\n if (this.isFunction()) {\n // if function has a parent, it needs local references\n if (!this.isRootLevel()) return true;\n\n // if function is in a shebang script, and at root level, no local references needed\n if (this.document.hasShebang()) return false;\n\n // if function is autoloaded, global, and matches autoload name, no local references needed\n if (\n this.document.isAutoloaded() &&\n this.isGlobal() &&\n this.name === this.document.getAutoLoadName()\n ) return false;\n\n // otherwise, function needs local references\n return true;\n }\n if (this.fishKind === 'ALIAS') return false;\n if (this.isVariable()) {\n if (SKIPPABLE_VARIABLE_REFERENCE_NAMES.includes(this.name)) return false;\n if (this.isExported()) return false;\n if (this.isGlobal()) return false;\n if (this.fishKind === 'FOR') return false;\n return true;\n }\n return false;\n }\n\n skippableVariableName(): boolean {\n if (!this.isVariable()) return false;\n return SKIPPABLE_VARIABLE_REFERENCE_NAMES.includes(this.name);\n }\n\n get path() {\n return uriToPath(this.uri);\n }\n\n get workspacePath() {\n const path = this.path;\n const pathItems = path.split('/');\n let lastItem = pathItems.at(-1)!;\n if (lastItem === 'config.fish') {\n return pathItems.slice(0, -1).join('/');\n }\n lastItem = pathItems.at(-2)!;\n if (['functions', 'completions', 'conf.d'].includes(lastItem)) {\n return pathItems.slice(0, -2).join('/');\n }\n return pathItems.slice(0, -1).join('/');\n }\n\n get scopeTag() {\n return this.scope.scopeTag;\n }\n\n /**\n * Enclosing SyntaxNode for symbols constraint inside of a local document\n * A global symbol will still have a scopeNode, but it should not be used to limit\n * the scope of a symbol. It is more common to limit the scope of a Symbol based\n * on if their is a redefined symbol (same name & type) inside of a smaller scope.\n */\n get scopeNode() {\n return this.scope.scopeNode;\n }\n\n // === Conversion Utils ===\n toString() {\n return SymbolConverters.symbolToString(this);\n }\n\n toWorkspaceSymbol(): WorkspaceSymbol {\n return SymbolConverters.symbolToWorkspaceSymbol(this);\n }\n\n toDocumentSymbol(): DocumentSymbol | undefined {\n return SymbolConverters.symbolToDocumentSymbol(this);\n }\n\n toLocation(): Location {\n return SymbolConverters.symbolToLocation(this);\n }\n\n toPosition(): Position {\n return SymbolConverters.symbolToPosition(this);\n }\n\n toFoldingRange(): FoldingRange {\n return SymbolConverters.symbolToFoldingRange(this);\n }\n\n toMarkupContent(): MarkupContent {\n return SymbolConverters.symbolToMarkupContent(this);\n }\n\n /**\n * Optionally include the current document's uri to the hover, this will determine\n * if a range is local to the current document (local ranges include hover range)\n */\n toHover(currentUri: DocumentUri = ''): Hover {\n return SymbolConverters.symbolToHover(this, currentUri);\n }\n\n // === FishSymbol type/location info ===\n isLocal() {\n return !this.isGlobal();\n }\n\n isGlobal() {\n return this.scope.scopeTag === 'global' || this.scope.scopeTag === 'universal';\n }\n\n isAutoloaded() {\n const doc = this.document.getAutoLoadName();\n if (!doc) return false;\n return this.name === doc && this.document.isAutoloaded() && this.isRootLevel();\n }\n\n isRootLevel() {\n // return isTopLevelDefinition(this.node);\n if (this.parent) {\n return false;\n }\n return !this.parent;\n }\n\n isEventHook(): boolean {\n return this.fishKind === 'FUNCTION_EVENT';\n }\n\n isEmittedEvent(): boolean {\n return this.fishKind === 'EVENT';\n }\n\n isEvent(): boolean {\n return FishKindGroups.EVENTS.includes(this.fishKind);\n }\n\n isFunction(): boolean {\n return FishKindGroups.FUNCTIONS.includes(this.fishKind);\n }\n\n isVariable(): boolean {\n return FishKindGroups.VARIABLES.includes(this.fishKind);\n }\n\n isArgparse(): boolean {\n return FishKindGroups.ARGPARSE.includes(this.fishKind);\n }\n\n isSymbolImmutable() {\n if (!config.fish_lsp_modifiable_paths.some(path => this.path.startsWith(path))) {\n return true;\n }\n return false;\n }\n\n //\n // Helpers for checking if the symbol is a fish_lsp_* config variable\n //\n\n /**\n * Checks if the symbol is a key in the `config` object, which means it changes the\n * configuration of the fish-lsp server.\n */\n isConfigDefinition() {\n if (this.kind !== SymbolKind.Variable || this.fishKind !== 'SET') {\n return false;\n }\n return Object.keys(config).includes(this.name);\n }\n\n /**\n * Checks if a config variable has the `--erase` option set\n */\n isConfigDefinitionWithErase() {\n if (!this.isConfigDefinition()) return false;\n const eraseOption = Option.create('-e', '--erase');\n const definitionNode = this.focusedNode;\n const children = findSetChildren(this.node)\n .filter(s => s.startIndex < definitionNode.startIndex);\n return children.some(s => isMatchingOption(s, eraseOption));\n }\n\n /**\n * Finds the value nodes of a config variable definition\n */\n findValueNodes(): SyntaxNode[] {\n const valueNodes: SyntaxNode[] = [];\n if (!this.isConfigDefinition()) return valueNodes;\n let node: null | SyntaxNode = this.focusedNode.nextNamedSibling;\n while (node) {\n if (!isEmptyString(node)) valueNodes.push(node);\n node = node.nextNamedSibling;\n }\n return valueNodes;\n }\n\n /**\n * Converts the value nodes of a config variable definition to shell values\n */\n valuesAsShellValues() {\n return this.findValueNodes().map(node => {\n return SyncFileHelper.expandEnvVars(FishString.fromNode(node));\n });\n }\n\n /**\n * Checks if both the current & other symbol define the same argparse flag, when\n * their is multiple equivalent _flag_names/_flag_n seen in the same argparse option.\n */\n equalArgparse(other: FishSymbol | CompletionSymbol) {\n if (FishSymbol.is(other)) {\n const equalNames = this.name !== other.name && this.aliasedNames.includes(other.name) && other.aliasedNames.includes(this.name);\n\n const equalParents = this.parent && other.parent\n ? this.parent.equals(other.parent)\n : !this.parent && !other.parent;\n\n return equalNames &&\n this.uri === other.uri &&\n this.fishKind === 'ARGPARSE' && other.fishKind === 'ARGPARSE' &&\n this.focusedNode.equals(other.focusedNode) &&\n this.node.equals(other.node) &&\n equalParents &&\n this.scopeNode.equals(other.scopeNode);\n }\n return false;\n }\n\n /**\n * A function that is autoloaded and includes an `event` hook\n *\n * ```fish\n * function my_function --on-event my_event\n * # ^^^^^^^^^^^-------------------- my_function would return true\n * end\n * ```\n */\n hasEventHook() {\n if (!this.isFunction()) return false;\n for (const child of this.children) {\n if (child.isEventHook()) {\n return true;\n }\n }\n return false;\n }\n\n /**\n * Checks if two symbols are equal events, excluding equality of the symbols\n * equaling the exact same symbol. Also ensures that one of the Symbols is a\n * event handler name, and the other is the emitted event name. Order does not\n * matter, allowing for either symbol to be the event handler or the emitted event.\n *\n * ```fish\n * function PARENT --on-event SYMBOL\n * # ^^^^^^---- This is the event handler definition name\n * end\n *\n * emit SYMBOL\n * # ^^^^^^-------------------------- This is the emitted event definition name\n * ```\n *\n * @param other - The other symbol to compare against\n * @return {boolean} - True if the symbols are equal events, false otherwise\n *\n */\n equalsEvent(other: FishSymbol | CompletionSymbol): boolean {\n if (!FishSymbol.is(other)) return false;\n if (!this.isEvent() || !other.isEvent()) return false;\n if (this.fishKind === other.fishKind) return false;\n\n // parent of the `function PARENT --on-event SYMBOL`\n const parent = this.fishKind === 'FUNCTION_EVENT'\n ? this.parent\n : other.parent;\n\n // child is the `emit SYMBOL` corresponding to the event in a function handler\n const child = this.fishKind === 'EVENT'\n ? this\n : other;\n\n // check if the parent and child exist and have same name\n return !!(parent && child && child.name === parent.name);\n }\n\n /**\n * The heavy lifting utility to determine if a node is a reference to the current\n * symbol.\n *\n * @param document The LspDocument to check against\n * @param node The SyntaxNode to check\n * @param excludeEqualNode If true, the node itself will not be considered a reference\n *\n * @returns {boolean} True if the node is a reference to the symbol, false otherwise\n */\n isReference(document: LspDocument, node: SyntaxNode, excludeEqualNode = false): boolean {\n return isSymbolReference(this, document, node, excludeEqualNode);\n }\n\n /**\n * Checks if 2 symbols are the same, based on their properties.\n */\n equals(other: FishSymbol): boolean {\n return equalSymbols(this, other);\n }\n\n /**\n * Checks if the symbol is the location.\n */\n equalsLocation(location: Location): boolean {\n return symbolEqualsLocation(this, location);\n }\n\n /**\n * Checks if a Symbol is defined in the same scope as its comparison symbol.\n */\n equalDefinition(other: FishSymbol): boolean {\n return equalSymbolDefinitions(this, other);\n }\n\n /**\n * Checks if the symbol is equal to the SyntaxNode\n * @param node The SyntaxNode to compare against\n * @param opts.strict If true, the comparison will be strict, meaning the node must match the symbol's focusedNode\n * Otherwise, a match can be either the focusedNode or the node itself.\n * @returns {boolean} True if the symbol is equal to the node, false otherwise\n */\n equalsNode(node: SyntaxNode, opts: { strict?: boolean; } = { strict: false }): boolean {\n return symbolEqualsNode(this, node, opts.strict);\n }\n\n /**\n * Checks if the symbol contains the other symbol's scope.\n * Here, the current Symbol must be ATLEAST equivalent parents to the other symbol\n * when the other symbol's Scope is not greater than the current symbol's scope.\n */\n containsScope(other: FishSymbol): boolean {\n return symbolContainsScope(this, other);\n }\n\n /**\n * Checks if the symbol has the same scope as the other symbol.\n */\n equalScopes(other: FishSymbol): boolean {\n return equalSymbolScopes(this, other);\n }\n\n /**\n * Checks if the symbol contains the node in its scope.\n */\n scopeContainsNode(node: SyntaxNode): boolean {\n return symbolScopeContainsNode(this, node);\n }\n\n /**\n * Checks if the symbol.range contains or is equal to the node's range.\n */\n containsNode(node: SyntaxNode): boolean {\n return symbolContainsNode(this, node);\n }\n\n /**\n * Check if the current symbols position contains or is equal to the given position\n * @param position The position to check against\n * @return {boolean} True if the symbol contains the position, false otherwise\n */\n containsPosition(position: { line: number; character: number; }): boolean {\n return symbolContainsPosition(this, position);\n }\n}\n\nexport type ModifierScopeTag = 'universal' | 'global' | 'function' | 'local' | 'inherit';\n\nexport const SetModifierToScopeTag = (modifier: Option): ModifierScopeTag => {\n switch (true) {\n case modifier.isOption('-U', '--universal'):\n return 'universal';\n case modifier.isOption('-g', '--global'):\n return 'global';\n case modifier.isOption('-f', '--function'):\n return 'function';\n case modifier.isOption('-l', '--local'):\n return 'local';\n default:\n return 'local';\n }\n};\n\nexport {\n FishSymbolKind,\n fromFishSymbolKindToSymbolKind,\n FishKindGroups,\n fishSymbolKindToSymbolKind,\n};\n\nexport function filterLastPerScopeSymbol(symbols: FishSymbol[]) {\n const flatArray: FishSymbol[] = flattenNested(...symbols);\n const array: FishSymbol[] = [];\n for (const symbol of symbols) {\n const lastSymbol = flatArray.findLast((s: FishSymbol) => {\n return s.name === symbol.name && s.kind === symbol.kind && s.uri === symbol.uri\n && s.equalScopes(symbol);\n });\n if (lastSymbol && lastSymbol.equals(symbol)) {\n array.push(symbol);\n }\n }\n return array;\n}\n\nexport function filterFirstPerScopeSymbol(document: LspDocument | DocumentUri): FishSymbol[] {\n const uri: DocumentUri = LspDocument.is(document) ? document.uri : document;\n const symbols = analyzer.getFlatDocumentSymbols(uri);\n const flatArray: FishSymbol[] = Array.from(symbols);\n\n const array: FishSymbol[] = [];\n for (const symbol of symbols) {\n const firstSymbol = flatArray.find((s: FishSymbol) => s.equalDefinition(symbol));\n if (firstSymbol && firstSymbol.equals(symbol)) {\n array.push(symbol);\n }\n }\n return array;\n}\n\nexport function filterFirstUniqueSymbolperScope(document: LspDocument | DocumentUri): FishSymbol[] {\n const uri: DocumentUri = LspDocument.is(document) ? document.uri : document;\n const symbols = analyzer.getFlatDocumentSymbols(uri);\n const result: FishSymbol[] = [];\n\n for (const symbol of symbols) {\n const alreadyExists = result.some(existing =>\n existing.name === symbol.name && existing.equalDefinition(symbol),\n );\n if (!alreadyExists) {\n result.push(symbol);\n }\n }\n\n return result;\n}\n\nexport function findLocalLocations(symbol: FishSymbol, allSymbols: FishSymbol[], includeSelf = true): Location[] {\n const result: SyntaxNode[] = [];\n /*\n * Here we need to handle aliases where there exists a function with the same name\n * (A very weird edge case)\n */\n const matchingNodes = allSymbols.filter(s => s.name === symbol.name && !symbol.equalScopes(s))\n .map(s => symbol.fishKind === 'ALIAS' ? s.node : s.scopeNode);\n\n for (const node of getChildNodes(symbol.scopeNode)) {\n /** skip nodes that would be considered a match for another symbol */\n if (matchingNodes.some(n => containsNode(n, node))) continue;\n if (symbol.isEqualLocation(node)) result.push(node);\n }\n return [\n includeSelf && symbol.name !== 'argv' ? symbol.toLocation() : undefined,\n ...result.map(node => symbol.fishKind === 'ARGPARSE'\n ? Location.create(symbol.uri, convertNodeRangeWithPrecedingFlag(node))\n : Location.create(symbol.uri, getRange(node)),\n ),\n ].filter(Boolean) as Location[];\n}\n\n/**\n * Formats a tree of FishSymbols into a string with proper indentation\n * @param symbols Array of FishSymbol objects to format\n * @param indentLevel Initial indentation level (optional, defaults to 0)\n * @returns A string representing the formatted tree\n */\nexport function formatFishSymbolTree(symbols: FishSymbol[], indentLevel: number = 0): string {\n let result = '';\n const indentString = ' '; // 2 spaces per indent level\n\n for (const symbol of symbols) {\n const indent = indentString.repeat(indentLevel);\n const scopeTag = symbol.scope?.scopeTag || 'unknown';\n result += `${indent}${symbol.name} (${symbol.fishKind}) (${scopeTag})\\n`;\n\n // Recursively format children with increased indent\n if (symbol.children && symbol.children.length > 0) {\n result += formatFishSymbolTree(symbol.children, indentLevel + 1);\n }\n }\n\n return result;\n}\n\nfunction buildNested(document: LspDocument, node: SyntaxNode, ...children: FishSymbol[]): FishSymbol[] {\n const firstNamedChild = node.firstNamedChild as SyntaxNode;\n const newSymbols: FishSymbol[] = [];\n\n switch (node.type) {\n case 'function_definition':\n newSymbols.push(...processFunctionDefinition(document, node, children));\n break;\n case 'for_statement':\n newSymbols.push(...processForDefinition(document, node, children));\n break;\n case 'command':\n if (isInlineVariableAssignment(node)) {\n // Inline variable assignments are handled elsewhere\n newSymbols.push(...processInlineVariables(document, node));\n break;\n }\n if (!firstNamedChild?.text) break;\n switch (firstNamedChild.text) {\n case 'set':\n newSymbols.push(...processSetCommand(document, node, children));\n break;\n case 'read':\n newSymbols.push(...processReadCommand(document, node, children));\n break;\n case 'argparse':\n newSymbols.push(...processArgparseCommand(document, node, children));\n break;\n case 'alias':\n newSymbols.push(...processAliasCommand(document, node, children));\n break;\n case 'export':\n newSymbols.push(...processExportCommand(document, node, children));\n break;\n case 'emit':\n newSymbols.push(...processEmitEventCommandName(document, node, children));\n break;\n default:\n break;\n }\n break;\n }\n return newSymbols;\n}\n\nexport type NestedFishSymbolTree = FishSymbol[];\nexport type FlatFishSymbolTree = FishSymbol[];\n\nexport function processNestedTree(document: LspDocument, ...nodes: SyntaxNode[]): NestedFishSymbolTree {\n const symbols: FishSymbol[] = [];\n\n /** add argv to script files */\n if (!document.isAutoloadedUri()) {\n const programNode = nodes.find(node => node.type === 'program');\n if (programNode) symbols.push(...processArgvDefinition(document, programNode));\n }\n\n for (const node of nodes) {\n // Process children first (bottom-up approach)\n const childSymbols = processNestedTree(document, ...node.children);\n\n // Process the current node and integrate children\n const newSymbols = buildNested(document, node, ...childSymbols);\n\n if (newSymbols.length > 0) {\n // If we created symbols for this node, add them (they should contain children)\n symbols.push(...newSymbols);\n } else if (childSymbols.length > 0) {\n // If no new symbols from this node but we have child symbols, bubble them up\n symbols.push(...childSymbols);\n }\n // If neither condition is met, we add nothing\n }\n\n return symbols;\n}\n"
},
{
"path": "src/parsing/unreachable.ts",
"content": "import { SyntaxNode } from 'web-tree-sitter';\nimport { isCommand, isReturn, isSwitchStatement, isCaseClause, isIfStatement, isForLoop, isFunctionDefinition, isComment, isConditionalCommand } from '../utils/node-types';\n\n/**\n * Checks if a node represents a control flow statement that terminates execution\n */\nfunction isTerminalStatement(node: SyntaxNode): boolean {\n if (isReturn(node)) return true;\n\n if (isCommand(node)) {\n const commandName = node.firstNamedChild?.text;\n return commandName === 'exit' || commandName === 'break' || commandName === 'continue';\n }\n\n // Also check if the node itself is a break/continue/exit/return keyword\n if (node.type === 'break' || node.type === 'continue' || node.type === 'exit' || node.type === 'return') {\n return true;\n }\n\n return false;\n}\n\n/**\n * Checks if a conditional_execution node contains a terminal statement\n */\nfunction conditionalExecutionTerminates(conditionalNode: SyntaxNode): boolean {\n // conditional_execution nodes directly contain the terminal statement\n // e.g., (conditional_execution (return (integer)))\n for (const child of conditionalNode.namedChildren) {\n if (isTerminalStatement(child)) {\n return true;\n }\n }\n return false;\n}\n\n/**\n * Checks if a conditional_execution represents an 'and' or 'or' operation\n * Fish uses both keyword forms (and/or) and operator forms (&&/||)\n */\nfunction getConditionalType(node: SyntaxNode): 'and' | 'or' | null {\n // Check all children for the operator (can be named or unnamed)\n for (const child of node.children) {\n // Fish keyword forms: 'and' or 'or' (named nodes)\n if (child.type === 'and') return 'and';\n if (child.type === 'or') return 'or';\n // Operator forms: '&&' or '||' (unnamed tokens)\n if (!child.isNamed) {\n if (child.text === '&&') return 'and';\n if (child.text === '||') return 'or';\n }\n }\n return null;\n}\n\n/**\n * Checks if a sequence of statements forms a complete and/or chain that terminates all paths\n * Pattern: command + and + or (or command + or + and) where both conditional branches terminate\n *\n * Example of unreachable:\n * echo a\n * and return 0\n * or return 1\n * echo \"unreachable\" # Both success and failure paths exit\n *\n * Example of reachable:\n * git rev-parse || return\n * echo \"reachable\" # Only failure path exits, success continues\n */\nfunction sequenceFormsTerminatingAndOrChain(nodes: SyntaxNode[], startIndex: number): boolean {\n // Need at least 3 nodes: initial command + and branch + or branch\n if (startIndex + 2 >= nodes.length) return false;\n\n const first = nodes[startIndex];\n const second = nodes[startIndex + 1];\n const third = nodes[startIndex + 2];\n\n // Pattern: command followed by two conditional_execution nodes\n if (!first || !second || !third) return false;\n\n const isCommandSequence = (isCommand(first) || isConditionalCommand(first)) &&\n isConditionalCommand(second) &&\n isConditionalCommand(third);\n\n if (!isCommandSequence) return false;\n\n // CRITICAL FIX: Must have BOTH 'and' and 'or' to terminate all paths\n // If we only have 'or' (or only 'and'), one path continues execution\n const secondType = getConditionalType(second);\n const thirdType = getConditionalType(third);\n\n // Must have both && and || (in either order)\n const hasBothOperators = secondType === 'and' && thirdType === 'or' ||\n secondType === 'or' && thirdType === 'and';\n\n if (!hasBothOperators) return false;\n\n // Both conditional executions must terminate\n const secondTerminates = conditionalExecutionTerminates(second);\n const thirdTerminates = conditionalExecutionTerminates(third);\n\n return secondTerminates && thirdTerminates;\n}\n\n/**\n * Checks if a case clause contains a terminal statement\n */\nfunction caseContainsTerminalStatement(caseNode: SyntaxNode): boolean {\n // Look through all children of the case clause (excluding the pattern)\n const caseBodyNodes: SyntaxNode[] = [];\n let skipPattern = true;\n\n for (const child of caseNode.namedChildren) {\n if (skipPattern) {\n skipPattern = false; // Skip the first child (the pattern)\n continue;\n }\n caseBodyNodes.push(child);\n }\n\n // Check if the sequence of statements in this case terminates all paths\n return sequenceTerminatesAllPaths(caseBodyNodes);\n}\n\n/**\n * Checks if a sequence of statements terminates all possible execution paths\n * This is the core logic for determining if code after this sequence is unreachable\n */\nfunction sequenceTerminatesAllPaths(nodes: SyntaxNode[]): boolean {\n for (const node of nodes) {\n // Skip comments\n if (isComment(node)) {\n continue;\n }\n\n // Direct terminal statements\n if (isTerminalStatement(node)) {\n return true;\n }\n\n // Complete if/else statements where all paths terminate\n if (isIfStatement(node) && allPathsTerminate(node)) {\n return true;\n }\n\n // Complete switch statements where all paths terminate\n if (isSwitchStatement(node) && allSwitchPathsTerminate(node)) {\n return true;\n }\n }\n return false;\n}\n\n/**\n * Checks if all code paths in an if statement terminate\n */\nfunction allPathsTerminate(ifNode: SyntaxNode): boolean {\n let hasElse = false;\n let ifBodyTerminates = false;\n let elseBodyTerminates = false;\n\n // Extract the different parts of the if statement\n const ifBodyNodes: SyntaxNode[] = [];\n let elseClauseNode: SyntaxNode | null = null;\n let skipCondition = true;\n\n for (const child of ifNode.namedChildren) {\n // Skip the condition parts (only the first condition)\n if (skipCondition && (child.type === 'command' || child.type === 'test_command' || child.type === 'command_substitution')) {\n skipCondition = false; // Only skip the very first condition\n continue;\n }\n\n // Check else clause\n if (child.type === 'else_clause') {\n hasElse = true;\n elseClauseNode = child;\n } else if (child.type !== 'else_if_clause') {\n // This is part of the if body\n ifBodyNodes.push(child);\n }\n }\n\n // Check if the if body terminates - must check if the sequence of statements terminates\n ifBodyTerminates = sequenceTerminatesAllPaths(ifBodyNodes);\n\n // Check if the else body terminates\n if (hasElse && elseClauseNode) {\n const elseBodyNodes = Array.from(elseClauseNode.namedChildren);\n elseBodyTerminates = sequenceTerminatesAllPaths(elseBodyNodes);\n }\n\n return ifBodyTerminates && hasElse && elseBodyTerminates;\n}\n\n/**\n * Checks if all paths in a switch statement terminate\n */\nfunction allSwitchPathsTerminate(switchNode: SyntaxNode): boolean {\n let hasDefault = false;\n let allCasesTerminate = true;\n\n for (const child of switchNode.namedChildren) {\n if (isCaseClause(child)) {\n // Check if this is the default case - look for '*' pattern\n const casePattern = child.firstNamedChild?.text;\n if (casePattern === '*' || casePattern === '\"*\"' || casePattern === \"'*'\" || casePattern === '\\\\*') {\n hasDefault = true;\n }\n\n // Check if this case terminates\n if (!caseContainsTerminalStatement(child)) {\n allCasesTerminate = false;\n }\n }\n }\n\n return hasDefault && allCasesTerminate;\n}\n\n/**\n * Gets all unreachable statements after a terminal statement in a sequence\n */\nfunction getUnreachableStatementsInSequence(nodes: SyntaxNode[]): SyntaxNode[] {\n const unreachable: SyntaxNode[] = [];\n let foundTerminal = false;\n\n for (let i = 0; i < nodes.length; i++) {\n const node = nodes[i]!;\n\n // Skip comments - they're allowed after terminal statements\n if (isComment(node)) {\n continue;\n }\n\n if (foundTerminal) {\n unreachable.push(node);\n continue;\n }\n\n // Check for direct terminal statements\n if (isTerminalStatement(node)) {\n foundTerminal = true;\n continue;\n }\n\n // Check for control structures that terminate all paths\n if (isIfStatement(node) && allPathsTerminate(node)) {\n foundTerminal = true;\n continue;\n }\n\n if (isSwitchStatement(node) && allSwitchPathsTerminate(node)) {\n foundTerminal = true;\n continue;\n }\n\n // Check for and/or chains: command + conditional_execution + conditional_execution\n if (sequenceFormsTerminatingAndOrChain(nodes, i)) {\n foundTerminal = true;\n // Skip the next 2 nodes since they're part of this pattern\n i += 2;\n continue;\n }\n }\n\n return unreachable;\n}\n\n/**\n * Finds unreachable code nodes in a function definition\n */\nfunction findUnreachableInFunction(functionNode: SyntaxNode): SyntaxNode[] {\n const unreachable: SyntaxNode[] = [];\n\n // Get the function body (all children except the function keyword and name)\n const functionBodyNodes: SyntaxNode[] = [];\n let foundFunctionKeyword = false;\n let foundFunctionName = false;\n\n for (const child of functionNode.namedChildren) {\n // Skip function keyword\n if (!foundFunctionKeyword && child.type === 'word' && child.text === 'function') {\n foundFunctionKeyword = true;\n continue;\n }\n // Skip function name (first word after 'function')\n if (foundFunctionKeyword && !foundFunctionName && child.type === 'word') {\n foundFunctionName = true;\n continue;\n }\n\n // Skip comments - they don't affect control flow\n if (isComment(child)) {\n continue;\n }\n\n functionBodyNodes.push(child);\n }\n\n // Find unreachable statements in the function body\n unreachable.push(...getUnreachableStatementsInSequence(functionBodyNodes));\n\n return unreachable;\n}\n\n/**\n * Finds unreachable code nodes in any block scope (if, for, etc.)\n */\nfunction findUnreachableInBlock(blockNode: SyntaxNode): SyntaxNode[] {\n const unreachable: SyntaxNode[] = [];\n\n // For if statements, we need to check each branch separately\n if (isIfStatement(blockNode)) {\n const ifBodyNodes: SyntaxNode[] = [];\n let elseClauseNode: SyntaxNode | null = null;\n let skipCondition = true;\n\n // Extract if body and else clause\n for (const child of blockNode.namedChildren) {\n // Skip only the FIRST condition part\n if (skipCondition && (child.type === 'command' || child.type === 'test_command' || child.type === 'command_substitution')) {\n skipCondition = false; // Only skip the very first condition\n continue;\n }\n\n if (child.type === 'else_clause') {\n elseClauseNode = child;\n } else if (child.type !== 'else_if_clause') {\n // This is part of the if body\n ifBodyNodes.push(child);\n }\n }\n\n // Check for unreachable code in the if body\n unreachable.push(...getUnreachableStatementsInSequence(ifBodyNodes));\n\n // Check for unreachable code in the else clause\n if (elseClauseNode) {\n const elseBodyNodes = Array.from(elseClauseNode.namedChildren);\n unreachable.push(...getUnreachableStatementsInSequence(elseBodyNodes));\n }\n } else if (isForLoop(blockNode)) {\n // For loops: skip the iterator variable and iterable, get the body\n const loopBodyNodes: SyntaxNode[] = [];\n let skipForParts = true;\n for (const child of blockNode.namedChildren) {\n // Skip \"for var in iterable\" parts\n if (skipForParts && (child.type === 'variable_name' || child.type === 'word' || child.type === 'command_substitution' || child.type === 'concatenation')) {\n continue;\n }\n skipForParts = false;\n loopBodyNodes.push(child);\n }\n unreachable.push(...getUnreachableStatementsInSequence(loopBodyNodes));\n } else {\n // For other block types, include all children\n const blockBodyNodes = Array.from(blockNode.namedChildren);\n unreachable.push(...getUnreachableStatementsInSequence(blockBodyNodes));\n }\n\n return unreachable;\n}\n\n/**\n * Recursively find unreachable code in a node and its descendants\n * This is more efficient than getChildNodes() because it only visits relevant nodes\n */\nfunction findUnreachableRecursive(node: SyntaxNode, unreachable: SyntaxNode[]): void {\n // Check the node itself for unreachable code\n if (isFunctionDefinition(node)) {\n unreachable.push(...findUnreachableInFunction(node));\n } else if (isIfStatement(node) || isForLoop(node)) {\n unreachable.push(...findUnreachableInBlock(node));\n }\n\n // Recursively check named children\n // This is much faster than getChildNodes() which does BFS over entire tree\n for (const child of node.namedChildren) {\n // Skip comments as they don't affect control flow\n if (isComment(child)) continue;\n\n // Recursively process child\n findUnreachableRecursive(child, unreachable);\n }\n}\n\n/**\n * Main function to find unreachable code nodes starting from a root node\n * Optimized to avoid full tree traversal via getChildNodes()\n */\nexport function findUnreachableCode(root: SyntaxNode): SyntaxNode[] {\n const unreachable: SyntaxNode[] = [];\n\n // Handle top-level program statements\n if (root.type === 'program') {\n const topLevelNodes = Array.from(root.namedChildren).filter(child => !isComment(child));\n const topLevelUnreachable = getUnreachableStatementsInSequence(topLevelNodes);\n unreachable.push(...topLevelUnreachable);\n }\n\n // Recursively traverse the tree (much faster than getChildNodes())\n findUnreachableRecursive(root, unreachable);\n\n return unreachable;\n}\n"
},
{
"path": "src/parsing/values.ts",
"content": "import { SyntaxNode } from 'web-tree-sitter';\nimport { FishSymbol } from './symbol';\nimport { isMatchingOption, isString } from '../utils/node-types';\nimport { FishString } from './string';\nimport { config } from '../config';\nimport { findSetChildren } from './set';\nimport { Option } from './options';\nimport { SyncFileHelper } from '../utils/file-operations';\nimport { SymbolKind } from 'vscode-languageserver';\n\n/**\n * Current implementation is for evaluating `config` keys, in non autoloaded\n * paths, but shown in the current workspace/document, in client.\n *\n * This will retrieve the values seen in a `set` definition, without\n * needing to extranally evaluate the definition via fish's source\n * command.\n *\n * Potential further implementation is ahead.\n */\n\nexport namespace LocalFishLspDocumentVariable {\n\n export function isConfigVariableDefinition(symbol: FishSymbol): boolean {\n if (symbol.kind !== SymbolKind.Variable || symbol.fishKind !== 'SET') {\n return false;\n }\n return Object.keys(config).includes(symbol.name);\n }\n\n export function isConfigVariableDefinitionWithErase(\n symbol: FishSymbol,\n ): boolean {\n if (!symbol.isConfigDefinition()) {\n return false;\n }\n return hasEraseFlag(symbol);\n }\n\n export function findValueNodes(symbol: FishSymbol) {\n const valueNodes: SyntaxNode[] = [];\n if (!symbol.isConfigDefinition()) return valueNodes;\n let node: null | SyntaxNode = symbol.focusedNode.nextNamedSibling;\n while (node) {\n if (!isEmptyString(node)) valueNodes.push(node);\n node = node.nextNamedSibling;\n }\n return valueNodes;\n }\n\n export function nodeToShellValue(node: SyntaxNode): string {\n return SyncFileHelper.expandEnvVars(FishString.fromNode(node));\n }\n\n export const eraseOption = Option.create('-e', '--erase');\n\n export function hasEraseFlag(symbol: FishSymbol): boolean {\n const definitionNode = symbol.focusedNode;\n // get only the flags. these are only allowed between the command `set` and the `variable_name`\n // i.e., set -gx foo value_1 || set --global --erase foo value_2\n // ^^^ ^^^^^^^^ ^^^^^^^ are the only matches\n const children = findSetChildren(symbol.node)\n .filter(s => s.startIndex < definitionNode.startIndex);\n\n return children.some(s => isMatchingOption(s, eraseOption));\n }\n}\n\nfunction isEmptyString(node: SyntaxNode) {\n return isString(node) && node.text.length === 2;\n}\n\nexport function configDefinitionParser(\n symbol: FishSymbol,\n) {\n const isDefinition = LocalFishLspDocumentVariable.isConfigVariableDefinition(symbol);\n const isDefinitionWithErase = LocalFishLspDocumentVariable.isConfigVariableDefinitionWithErase(symbol);\n const valueNodes = LocalFishLspDocumentVariable.findValueNodes(symbol);\n const values = valueNodes.map(node => LocalFishLspDocumentVariable.nodeToShellValue(node));\n return {\n isDefinition,\n isErase: isDefinitionWithErase,\n valueNodes,\n values,\n };\n}\n"
},
{
"path": "src/references.ts",
"content": "import { DocumentUri, Location, Position, Range, WorkDoneProgressReporter } from 'vscode-languageserver';\nimport { analyzer } from './analyze';\nimport { LspDocument } from './document';\nimport { findParentCommand, findParentFunction, isCommandName, isCommandWithName, isMatchingOption, isOption, isProgram, isString } from './utils/node-types';\nimport { containsNode, getRange, nodesGen } from './utils/tree-sitter';\nimport { filterFirstPerScopeSymbol, FishSymbol } from './parsing/symbol';\nimport { isMatchingOptionOrOptionValue, Option } from './parsing/options';\nimport { logger } from './logger';\nimport { getGlobalArgparseLocations } from './parsing/argparse';\nimport { SyntaxNode } from 'web-tree-sitter';\nimport * as Locations from './utils/locations';\nimport { Workspace } from './utils/workspace';\nimport { workspaceManager } from './utils/workspace-manager';\nimport { uriToReadablePath } from './utils/translation';\nimport { FishAlias, isAliasDefinitionValue } from './parsing/alias';\nimport { extractCommandLocations, extractCommands, extractMatchingCommandLocations } from './parsing/nested-strings';\nimport { isEmittedEventDefinitionName } from './parsing/emit';\n\n// ┌──────────────────────────────────┐\n// │ file handles 3 main operations: │\n// │ • getReferences() │\n// │ • allUnusedLocalReferences() │\n// │ • getImplementations() │\n// └──────────────────────────────────┘\n\n/**\n * Options for the getReferences function\n */\nexport type ReferenceOptions = {\n // don't include the definition of the symbol itself\n excludeDefinition?: boolean;\n // only check local references inside the current document\n localOnly?: boolean;\n // stop searching after the first match\n firstMatch?: boolean;\n // search in all workspaces, default is to search only the current workspace\n allWorkspaces?: boolean;\n // only consider matches in the specified files\n onlyInFiles?: ('conf.d' | 'functions' | 'config' | 'completions')[];\n // log performance, show timing of the function\n logPerformance?: boolean;\n // enable logging for the function\n loggingEnabled?: boolean;\n\n reporter?: WorkDoneProgressReporter; // callback to report the number of references found\n};\n\n/**\n * get all the references for a symbol, including the symbol's definition\n * @param analyzer the analyzer\n * @param document the document\n * @param position the position of the symbol\n * @param localOnly if true, only return local references inside current document\n * @return the locations of the symbol\n */\nexport function getReferences(\n document: LspDocument,\n position: Position,\n opts: ReferenceOptions = {\n excludeDefinition: false,\n localOnly: false,\n firstMatch: false,\n allWorkspaces: false,\n onlyInFiles: [],\n logPerformance: true,\n loggingEnabled: false,\n reporter: undefined,\n },\n): Location[] {\n const results: Location[] = [];\n const logCallback = logWrapper(document, position, opts);\n\n // Get the Definition Symbol of the current position, if there isn't one\n // we can't find any references\n const definitionSymbol = analyzer.getDefinition(document, position);\n if (!definitionSymbol) {\n logCallback(\n `No definition symbol found for position ${JSON.stringify(position)} in document ${document.uri}`,\n 'warning',\n );\n return [];\n }\n\n // include the definition symbol itself\n if (!opts.excludeDefinition) results.push(definitionSymbol.toLocation());\n\n // if the symbol is local, we only search in the current document\n if (isSymbolLocalToDocument(definitionSymbol)) opts.localOnly = true;\n\n // create a list of al documents we will search for references\n const documentsToSearch: LspDocument[] = getDocumentsToSearch(document, logCallback, opts);\n\n // analyze the CompletionSymbol's and add their locations to result array\n // this is separate from the search operation because analysis lazy loads\n // completion documents (completion files are skipped during the initial workspace load)\n if (definitionSymbol.isArgparse() || definitionSymbol.isFunction()) {\n results.push(...getGlobalArgparseLocations(definitionSymbol.document, definitionSymbol));\n }\n if (\n definitionSymbol.isFunction()\n && definitionSymbol.hasEventHook()\n && definitionSymbol.document.isAutoloaded()\n ) {\n results.push(...analyzer.findSymbols((d, _) => {\n if (d.isEmittedEvent() && d.name === definitionSymbol.name) {\n return true;\n }\n return false;\n }).map(d => d.toLocation()));\n }\n\n // convert the documentsToSearch to a Set for O(1) lookups\n const searchableDocumentsUris = new Set(documentsToSearch.map(doc => doc.uri));\n const searchableDocuments = new Set(documentsToSearch.filter(doc => searchableDocumentsUris.has(doc.uri)));\n\n // dictionary where we will store the references found, used to build the results\n const matchingNodes: { [document: DocumentUri]: SyntaxNode[]; } = {};\n\n // boolean to control stopping our search when opts.firstMatch is true\n let shouldExitEarly = false;\n\n // utils for reporting progress during large searches of references\n let reporting = false;\n const reporter = opts.reporter;\n\n // if we have a reporter, we will report the progress of the search\n if (opts.reporter && searchableDocuments.size > 500) {\n reporter?.begin('[fish-lsp] finding references', 0, 'Finding references...', true);\n reporting = true;\n }\n\n let index = 0;\n // search the valid documents for references and store matches to build after\n // we have collected all valid matches for the requested options\n for (const doc of searchableDocuments) {\n const prog = Math.ceil((index + 1) / searchableDocuments.size * 100);\n if (reporting) {\n reporter?.report(prog);\n }\n index += 1;\n\n if (!workspaceManager.current?.contains(doc.uri)) {\n continue;\n }\n\n const filteredSymbols = getFilteredLocalSymbols(definitionSymbol, doc);\n\n const root = analyzer.getRootNode(doc.uri);\n if (!root) {\n logCallback(`No root node found for document ${doc.uri}`, 'warning');\n continue;\n }\n const matchableNodes = getChildNodesOptimized(definitionSymbol, doc);\n\n for (const node of matchableNodes) {\n // skip nodes that are redefinitions of the symbol in the local scope\n if (filteredSymbols && filteredSymbols.some(s => s.containsNode(node) || s.scopeNode.equals(node) || s.scopeContainsNode(node))) {\n continue;\n }\n // store matches in the matchingNodes dictionary\n if (definitionSymbol.isReference(doc, node, true)) {\n const currentDocumentsNodes = matchingNodes[doc.uri] ?? [];\n currentDocumentsNodes.push(node);\n matchingNodes[doc.uri] = currentDocumentsNodes;\n if (opts.firstMatch) {\n shouldExitEarly = true; // stop searching after the first match\n break;\n }\n }\n }\n if (shouldExitEarly) break;\n }\n\n // now convert the matching nodes to locations\n for (const [uri, nodes] of Object.entries(matchingNodes)) {\n for (const node of nodes) {\n const locations = getLocationWrapper(definitionSymbol, node, uri)\n .filter(loc => !results.some(location => Locations.Location.equals(loc, location)));\n results.push(...locations);\n }\n }\n\n // log the results, if logging option is enabled\n const docShorthand = `${workspaceManager.current?.name}`;\n const count = results.length;\n const name = definitionSymbol.name;\n logCallback(\n `Found ${count} references for symbol '${name}' in document '${docShorthand}'`,\n 'info',\n );\n\n if (reporting) reporter?.done();\n\n const sorter = locationSorter(definitionSymbol);\n return results.sort(sorter);\n}\n\n/**\n * Returns all unused local references in the current document.\n */\nexport function allUnusedLocalReferences(document: LspDocument): FishSymbol[] {\n // const allSymbols = analyzer.getFlatDocumentSymbols(document.uri);\n\n const symbols = filterFirstPerScopeSymbol(document).filter(s =>\n s.isLocal()\n && s.name !== 'argv'\n && !s.isEventHook()\n && !s.isExported(),\n );\n\n if (!symbols) return [];\n\n const usedSymbols: FishSymbol[] = [];\n const unusedSymbols: FishSymbol[] = [];\n\n for (const symbol of symbols) {\n const localSymbols = getFilteredLocalSymbols(symbol, document);\n\n let found = false;\n const root = analyzer.getRootNode(document.uri);\n if (!root) {\n logger.warning(`No root node found for document ${document.uri}`);\n continue;\n }\n for (const node of nodesGen(root)) {\n // skip nodes that are redefinitions of the symbol in the local scope\n if (localSymbols?.some(c => c.scopeContainsNode(node))) {\n continue;\n }\n if (symbol.isReference(document, node, true)) {\n found = true;\n usedSymbols.push(symbol);\n break;\n }\n }\n if (!found) unusedSymbols.push(symbol);\n }\n\n // Confirm that the unused symbols are not referenced by any used symbols for edge cases\n // where names don't match, but the symbols are meant to overlap in usage:\n //\n // `argparse h/help`/`_flag_h`/`_flag_help`/`complete -s h -l help`\n // `function event_handler --on-event my_event`/`emit my_event # usage of event_handler`\n //\n const finalUnusedSymbols = unusedSymbols.filter(symbol => {\n if (symbol.isArgparse() && usedSymbols.some(s => s.equalArgparse(symbol))) {\n return false;\n }\n if (symbol.hasEventHook()) {\n if (symbol.isGlobal()) return false;\n if (\n symbol.isLocal()\n && symbol.children.some(c => c.fishKind === 'FUNCTION_EVENT' && usedSymbols.some(s => s.isEmittedEvent() && c.name === s.name))\n ) {\n return false;\n }\n // for a function that should be treated locally, but a event that is emitted globally in another doc\n if (symbol.document.isAutoloaded() && symbol.isFunction() && symbol.hasEventHook()) {\n const eventsEmitted = symbol.children.filter(c => c.isEventHook());\n for (const event of eventsEmitted) {\n if (analyzer.findNode(n => isEmittedEventDefinitionName(n) && n.text === event.name)) {\n return false;\n }\n }\n }\n }\n return true;\n });\n logger.debug({\n usage: 'finalUnusedLocalReferences',\n finalUnusedSymbols: finalUnusedSymbols.map(s => s.name),\n });\n\n return finalUnusedSymbols;\n}\n\n/**\n * bi-directional jump to either definition or completion definition\n * @param analyzer the analyzer\n * @param document the document\n * @param position the position of the symbol\n * @return the locations of the symbol, should be a lower number of locations than getReferences\n */\nexport function getImplementation(\n document: LspDocument,\n position: Position,\n): Location[] {\n const locations: Location[] = [];\n const node = analyzer.nodeAtPoint(document.uri, position.line, position.character);\n if (!node) return [];\n const symbol = analyzer.getDefinition(document, position);\n if (!symbol) return [];\n if (symbol.isEmittedEvent()) {\n const result = analyzer.findSymbol((s, _) =>\n s.isEventHook() && s.name === symbol.name,\n )?.toLocation();\n if (result) {\n locations.push(result);\n return locations;\n }\n }\n if (symbol.isEventHook()) {\n const result = analyzer.findSymbol((s, _) =>\n s.isEmittedEvent() && s.name === symbol.name,\n )?.toLocation();\n if (result) {\n locations.push(result);\n return locations;\n }\n }\n\n const newLocations = getReferences(document, position)\n .filter(location => location.uri !== document.uri);\n\n if (newLocations.some(s => s.uri === symbol.uri)) {\n locations.push(symbol.toLocation());\n return locations;\n }\n if (newLocations.some(s => s.uri.includes('completions/'))) {\n locations.push(newLocations.find(s => s.uri.includes('completions/'))!);\n return locations;\n }\n locations.push(symbol.toLocation());\n return locations;\n}\n\n/**\n * Returns the location of a node, based on the symbol.\n * Handles special cases where a reference might be part of a larger token from tree-sitter.\n *\n * For example, in argparse switches, we want to return the location of the flag name which\n * might include a short flag and a long flag like:\n *\n * ```fish\n * argparse h/help -- $argv # we might want 'h' or 'help' specifically, fish tokenizes the 'h/help' together\n * ```\n *\n * @param symbol the definition symbol for which we are searching for references\n * @param node the tree-sitter node that matches the symbol\n * @param uri the document URI of the node (for global symbols, the URI might not match the symbol's URI)\n * @return an array of locations for the node, most commonly a single item is returned in the array\n */\nfunction getLocationWrapper(symbol: FishSymbol, node: SyntaxNode, uri: DocumentUri): Location[] {\n let range = getRange(node);\n // for argparse flags, we want the range of the flag name, not the whole option\n if (symbol.fishKind === 'ARGPARSE' && isOption(node)) {\n range = {\n start: {\n line: range.start.line,\n character: range.start.character + getLeadingDashCount(node),\n },\n end: {\n line: range.end.line,\n character: range.end.character + 1,\n },\n };\n return [Location.create(uri, range)];\n }\n if (isAliasDefinitionValue(node)) {\n const parent = findParentCommand(node);\n if (!parent) return [];\n\n const info = FishAlias.getInfo(parent);\n if (!info) return [];\n\n const aliasRange = extractCommandRangeFromAliasValue(node, symbol.name);\n if (aliasRange) {\n range = aliasRange;\n }\n return [Location.create(uri, range)];\n }\n if (NestedSyntaxNodeWithReferences.isBindCall(symbol, node)) {\n return extractMatchingCommandLocations(symbol, node, uri);\n }\n if (NestedSyntaxNodeWithReferences.isCompleteConditionCall(symbol, node)) {\n return extractMatchingCommandLocations(symbol, node, uri);\n }\n if (symbol.isFunction() && (isString(node) || isOption(node))) {\n return extractCommandLocations(node, uri)\n .filter(loc => loc.command === symbol.name)\n .map(loc => loc.location);\n }\n return [Location.create(uri, range)];\n}\n\n/**\n * Counts the number of leading dashes in a node's text\n * This is used to determine the range of an option flag in an argparse's completion or usage\n * @param node the completion node to check\n * @return the number of leading dashes in the node's text\n */\nfunction getLeadingDashCount(node: SyntaxNode): number {\n if (!node || !node.text) return 0;\n\n const text = node.text;\n let count = 0;\n\n for (let i = 0; i < text.length; i++) {\n if (text[i] === '-') {\n count++;\n } else {\n break;\n }\n }\n\n return count;\n}\n\n/**\n * Namespace for checking SyntaxNode references are of a specific type\n * • `alias foo=''`\n * • `bind ctrl-space ''`\n * • `complete -c foo -n '' -xa '1 2 3'`\n */\nexport namespace NestedSyntaxNodeWithReferences {\n export function isAliasValueNode(definitionSymbol: FishSymbol, node: SyntaxNode): boolean {\n if (!isAliasDefinitionValue(node)) return false;\n const parent = findParentCommand(node);\n if (!parent) return false;\n const info = FishAlias.getInfo(parent);\n if (!info) return false;\n const infoCmds = info.value.split(';').map(cmd => cmd.trim().split(' ').at(0));\n return infoCmds.includes(definitionSymbol.name);\n }\n\n export function isBindCall(definitionSymbol: FishSymbol, node: SyntaxNode): boolean {\n if (!node?.parent || isOption(node)) return false;\n const parent = findParentCommand(node);\n if (!parent || !isCommandWithName(parent, 'bind')) return false;\n const subcommands = parent.children.slice(2).filter(c => !isOption(c));\n if (!subcommands.some(c => c.equals(node))) return false;\n const cmds = extractCommands(node);\n return cmds.some(cmd => cmd === definitionSymbol.name);\n }\n\n export function isCompleteConditionCall(definitionSymbol: FishSymbol, node: SyntaxNode): boolean {\n if (isOption(node) || !node.isNamed || isProgram(node)) return false; // skip options\n if (!node.parent || !isCommandWithName(node.parent, 'complete')) return false;\n if (!node?.previousSibling || !isMatchingOption(node?.previousSibling, Option.fromRaw('-n', '--condition'))) return false;\n const cmds = extractCommands(node);\n logger.debug(`Extracted commands from complete condition node: ${cmds}`);\n return !!cmds.some(cmd => cmd.trim() === definitionSymbol.name);\n }\n\n export function isWrappedCall(definitionSymbol: FishSymbol, node: SyntaxNode): boolean {\n if (!node?.parent || !findParentFunction(node)) return false;\n if (node.previousNamedSibling && isMatchingOption(node.previousNamedSibling, Option.fromRaw('-w', '--wraps'))) {\n const cmds = extractCommands(node);\n logger.debug(`Extracted commands from wrapped call node: ${cmds}`);\n return cmds.some(cmd => cmd.trim() === definitionSymbol.name);\n }\n if (isMatchingOptionOrOptionValue(node, Option.fromRaw('-w', '--wraps'))) {\n logger.warning(`Node ${node.text} is a wrapped call for symbol ${definitionSymbol.name}`);\n const cmds = extractCommands(node);\n logger.debug(`Extracted commands from wrapped call node: ${cmds}`);\n return cmds.some(cmd => cmd.trim() === definitionSymbol.name);\n }\n return false;\n }\n\n export function isAnyNestedCommand(definitionSymbol: FishSymbol, node: SyntaxNode): boolean {\n return isAliasValueNode(definitionSymbol, node)\n || isBindCall(definitionSymbol, node)\n || isCompleteConditionCall(definitionSymbol, node);\n }\n}\n\n/**\n * Checks if a symbol will only include references local to the current document\n *\n * If a symbol is global, or it might be referenced in other documents (i.e., `argparse`)\n * then it is not considered local to the document.\n *\n * @param symbol the symbol to check\n * @return true if the symbol's references can only be local to the document, false otherwise\n */\nfunction isSymbolLocalToDocument(symbol: FishSymbol): boolean {\n if (symbol.isGlobal()) return false;\n if (symbol.isLocal() && symbol.isArgparse()) {\n const parent = symbol.parent;\n // argparse flags that are inside a global function might have completions,\n // so we don't consider them local to the document\n if (parent && parent.isGlobal()) return false;\n }\n if (symbol.document.isAutoloaded()) {\n if (symbol.isFunction() || symbol.hasEventHook()) {\n // functions and event hooks that are autoloaded are considered global\n return false;\n }\n if (symbol.isEvent()) {\n return false; // global event hooks are not local to the document\n }\n }\n\n // symbols that are not explicitly defined as global, will reach this point\n // thus, we consider them local to the document\n return true;\n}\n\n/**\n * Extracts the precise range of a command reference within an alias definition value\n * Only matches commands in command position, not as arguments\n */\nfunction extractCommandRangeFromAliasValue(node: SyntaxNode, commandName: string): Range | null {\n const text = node.text;\n let searchText = text;\n let baseOffset = 0;\n\n // Handle different alias value formats\n if (text.includes('=')) {\n // Format: name=value\n const equalsIndex = text.indexOf('=');\n searchText = text.substring(equalsIndex + 1);\n baseOffset = equalsIndex + 1;\n }\n\n // Remove surrounding quotes if present\n if (searchText.startsWith('\"') && searchText.endsWith('\"') ||\n searchText.startsWith(\"'\") && searchText.endsWith(\"'\")) {\n searchText = searchText.slice(1, -1);\n baseOffset += 1;\n }\n\n // Find command positions using shell command structure analysis\n const commandMatches = findCommandPositions(searchText, commandName);\n\n if (commandMatches.length === 0) return null;\n\n // For now, return the first command match (you could return all if needed)\n const firstMatch = commandMatches[0];\n if (!firstMatch) return null;\n\n const startOffset = baseOffset + firstMatch.start;\n const endOffset = startOffset + commandName.length;\n\n return Range.create(\n node.startPosition.row,\n node.startPosition.column + startOffset,\n node.startPosition.row,\n node.startPosition.column + endOffset,\n );\n}\n\n/**\n * Finds positions where a command name appears as an actual command (not as an argument)\n */\nfunction findCommandPositions(shellCode: string, commandName: string): Array<{ start: number; end: number; }> {\n const matches: Array<{ start: number; end: number; }> = [];\n\n // Split by command separators: ; && || & | (pipes and logical operators)\n const commandSeparators = /([;&|]+|\\s*&&\\s*|\\s*\\|\\|\\s*)/;\n const parts = shellCode.split(commandSeparators);\n\n let currentOffset = 0;\n\n for (const part of parts) {\n if (!part || commandSeparators.test(part)) {\n // This is a separator, skip it\n currentOffset += part.length;\n continue;\n }\n\n // Clean up whitespace and find the first word (command)\n const trimmedPart = part.trim();\n const partStartOffset = currentOffset + part.indexOf(trimmedPart);\n\n if (trimmedPart) {\n // Extract the first word as the command\n const firstWordMatch = trimmedPart.match(/^([^\\s]+)/);\n if (firstWordMatch) {\n const firstWord = firstWordMatch[1];\n if (firstWord === commandName) {\n matches.push({\n start: partStartOffset,\n end: partStartOffset + commandName.length,\n });\n }\n }\n }\n\n currentOffset += part.length;\n }\n\n return matches;\n}\n/**\n * Optimized version of getChildNodes that pre-filters by text content\n * This significantly reduces the number of nodes we need to check\n */\nfunction* getChildNodesOptimized(symbol: FishSymbol, doc: LspDocument): Generator {\n const root = analyzer.getRootNode(doc.uri);\n if (!root) return;\n\n const localSymbols = analyzer.getFlatDocumentSymbols(doc.uri)\n .filter(s => {\n if (s.uri === doc.uri) return false;\n if (s.isFunction() && s.isLocal() && s.name === symbol.name && symbol.isFunction()) {\n return !s.equals(symbol);\n }\n return s.name === symbol.name\n && s.kind === symbol.kind\n && s.isLocal()\n && !symbol.equalDefinition(s);\n });\n\n const skipNodes = localSymbols.map(s => s.parent?.node).filter(n => n !== undefined) as SyntaxNode[];\n\n const isPotentialMatch = (current: SyntaxNode) => {\n if (symbol.isArgparse()\n && (isOption(current) || current.text === symbol.name || current.text === symbol.argparseFlagName)\n ) {\n return true;\n } else if (symbol.name === current.text) {\n return true;\n } else if (isString(current)) {\n return true;\n }\n if (symbol.isFunction()) {\n return symbol.name === current.text\n || isCommandName(current)\n || current.type === 'word'\n || current.isNamed;\n }\n return false;\n };\n\n const queue: SyntaxNode[] = [root];\n\n while (queue.length > 0) {\n const current = queue.shift();\n if (!current) continue;\n\n if (\n skipNodes && skipNodes.some(s =>\n containsNode(s, current) || s.equals(current) && !isProgram(current),\n )) {\n continue;\n }\n\n if (isPotentialMatch(current)) {\n yield current;\n }\n // Add children to queue for processing\n if (current.children.length > 0) {\n queue.unshift(...current.children);\n }\n }\n}\n/**\n * Returns a list of documents to search for references based on the options provided.\n *\n * @param document the document to search in\n * @param logCallback the logging callback function\n * @param opts the options for searching references\n * @return an array of documents to search for references\n */\nfunction getDocumentsToSearch(\n document: LspDocument,\n logCallback: ReturnType,\n opts: ReferenceOptions,\n): LspDocument[] {\n let documentsToSearch: LspDocument[] = [];\n if (opts.localOnly) {\n documentsToSearch.push(document);\n } else if (opts.allWorkspaces) {\n workspaceManager.all.forEach((ws: Workspace) => {\n documentsToSearch.push(...ws.allDocuments());\n });\n } else {\n // default to using the current workspace\n let currentWorkspace = workspaceManager.current;\n if (!currentWorkspace) {\n currentWorkspace = workspaceManager.findContainingWorkspace(document.uri) || undefined;\n if (!currentWorkspace) {\n logCallback(`No current workspace found for document ${document.uri}`, 'warning');\n return [document];\n }\n }\n currentWorkspace?.allDocuments().forEach((doc: LspDocument) => {\n documentsToSearch.push(doc);\n });\n }\n\n // filter out documents that don't match the specified file types\n if (opts.onlyInFiles && opts.onlyInFiles.length > 0) {\n documentsToSearch = documentsToSearch.filter(doc => {\n const fileType = doc.getAutoloadType();\n if (!fileType) return false;\n return opts.onlyInFiles!.includes(fileType);\n });\n }\n\n return documentsToSearch;\n}\n\n/**\n * Callback wrapper function for logging the getReferences function,\n * so that the parent function doesn't have to handle logging directly.\n *\n * Forwards the getReferences(params) to this function.\n *\n * Calls the logger.info/debug/warning/error methods with the request and params.\n */\nfunction logWrapper(\n document: LspDocument,\n position: Position,\n opts: ReferenceOptions,\n) {\n const posStr = `{line: ${position.line}, character: ${position.character}}`;\n const requestMsg = `getReferencesNew(params) -> ${new Date().toISOString()}`;\n const params = {\n uri: uriToReadablePath(document.uri),\n position: posStr,\n opts: opts,\n };\n const startTime = performance.now();\n\n return function(message: string, level: 'info' | 'debug' | 'warning' | 'error' = 'info') {\n if (!opts.loggingEnabled) return; // If logging is disabled\n const endTime = performance.now();\n const duration = ((endTime - startTime) / 1000).toFixed(2); // Convert to seconds with 2 decimal places\n const logObj: {\n request: string;\n params: typeof params;\n message: string;\n // duration?: string;\n } = {\n request: requestMsg,\n params,\n message,\n // duration: opts.logPerformance ? `duration: ${duration} seconds` : undefined,\n };\n\n switch (level) {\n case 'info':\n logger.info(logObj, duration);\n break;\n case 'debug':\n logger.debug(logObj, duration);\n break;\n case 'warning':\n logger.warning(logObj, duration);\n break;\n case 'error':\n logger.error({\n ...logObj,\n message: `Error: ${message}`,\n duration,\n });\n break;\n default:\n logger.warning({\n ...logObj,\n message: `Unknown log level: ${level}. Original message: ${message}`,\n duration,\n });\n break;\n }\n logger.debug(`DURATION: ${duration}`, { uri: uriToReadablePath(document.uri), position: posStr });\n };\n}\n\n/**\n * Sorts the references based on their proximity to the definition symbol,\n * Sorting by:\n * 1. Definition Symbol URI (and local references)\n * 2. Go to implementation URI (functions/ <-> completions/)\n * 3. References Grouped by order of URI seen in Workspace Search\n * 4. Position (Top to Bottom, Left to Right)\n */\nconst locationSorter = (defSymbol: FishSymbol) => {\n const getUriPriority = (defSymbol: FishSymbol) => {\n return (uri: DocumentUri) => {\n let basePriority = 10; // default\n\n if (defSymbol.isArgparse()) {\n if (uri === defSymbol.uri) basePriority = 100;\n else if (uri.includes('completions/')) basePriority = 50;\n } else if (defSymbol.isFunction()) {\n if (uri === defSymbol.uri) basePriority = 100;\n else if (uri.includes('completions/')) basePriority = 50;\n } else if (defSymbol.isVariable()) {\n if (uri === defSymbol.uri) basePriority = 100;\n }\n\n // Add a small fraction based on URI string for consistent ordering\n const uriHash = uri.split('').reduce((acc, char) => acc + char.charCodeAt(0), 0);\n return basePriority + uriHash % 1000 / 10000; // keeps string order as decimal\n };\n };\n\n const uriPriority = getUriPriority(defSymbol);\n\n return function(a: Location, b: Location) {\n const aUriPriority = uriPriority(a.uri);\n const bUriPriority = uriPriority(b.uri);\n\n if (aUriPriority !== bUriPriority) {\n return bUriPriority - aUriPriority; // higher priority first\n }\n\n // same URI, sort by position\n if (a.range.start.line !== b.range.start.line) {\n return a.range.start.line - b.range.start.line;\n }\n return a.range.start.character - b.range.start.character;\n };\n};\n\nexport const getFilteredLocalSymbols = (definitionSymbol: FishSymbol, doc: LspDocument) => {\n if (definitionSymbol.isVariable() && !definitionSymbol.isArgparse()) {\n // if the symbol is a variable, we only want to find references in the current document\n return analyzer.getFlatDocumentSymbols(doc.uri)\n .filter(\n s => s.isLocal()\n && !s.equals(definitionSymbol)\n && !definitionSymbol.equalScopes(s)\n // && !s.parent?.equals(definitionSymbol?.parent || definitionSymbol)\n && s.name === definitionSymbol.name\n && s.kind === definitionSymbol.kind,\n );\n }\n if (doc.uri === definitionSymbol.uri) return [];\n return analyzer.getFlatDocumentSymbols(doc.uri)\n .filter(s =>\n s.isLocal()\n && s.name === definitionSymbol.name\n && s.kind === definitionSymbol.kind\n && !s.equals(definitionSymbol),\n );\n};\n"
},
{
"path": "src/renames.ts",
"content": "import { getReferences } from './references';\nimport { analyzer, Analyzer } from './analyze';\nimport { Position, Range } from 'vscode-languageserver';\nimport { LspDocument } from './document';\nimport { FishSymbol } from './parsing/symbol';\nimport { logger } from './logger';\n\nexport type FishRenameLocationType = 'variable' | 'function' | 'command' | 'argparse' | 'flag';\n\nexport interface FishRenameLocation {\n uri: string;\n range: Range;\n type: FishRenameLocationType;\n newText: string;\n}\n\nexport function getRenames(\n doc: LspDocument,\n position: Position,\n newText: string,\n): FishRenameLocation[] {\n const symbol = analyzer.getDefinition(doc, position);\n if (!symbol || !newText) return [];\n if (!canRenameWithNewText(analyzer, doc, position, newText)) return [];\n newText = fixNewText(symbol, position, newText);\n const locs = getReferences(doc, position);\n return locs.map(loc => {\n const locationText = analyzer.getTextAtLocation(loc);\n let replaceText = newText || locationText;\n if (locationText.startsWith('_flag_') && symbol.fishKind === 'ARGPARSE') {\n loc.range.start.character += '_flag_'.length;\n if (newText?.includes('-')) {\n replaceText = newText.replace(/-/g, '_');\n }\n }\n if (locationText.includes('=') && symbol.fishKind === 'ARGPARSE') {\n loc.range.end.character = loc.range.start.character + locationText.indexOf('=');\n }\n return {\n uri: loc.uri,\n range: loc.range,\n type: symbol.fishKind as FishRenameLocationType,\n newText: replaceText,\n };\n });\n}\n\n/**\n * Currently for rename requests that are for an argparse FishSymbol,\n * that are from a request that is not on the symbol definition.\n * ```fish\n * function foo\n * argparse 'values-with=?' -- $argv\n * or return\n *\n * if set -ql _flag_values_with\n * end\n * end\n *\n * foo --values-with\n * ```\n *\n * Case 1.) the rename request is on `_flag_values_with`, we need to remove the\n * leading `_flag_` from the newText\n *\n * Case 2.) the rename request is on `--values-with`, we need to remove the leading `--`\n */\nfunction fixNewText(symbol: FishSymbol, position: Position, newText: string) {\n // EDGE CASE 1: rename on a flag usage: _flag_values_with\n // would still work if the rename request is under `argparse 'values-with=?'`\n // So, we need a check for if the newText starts with _flag_, then we trim off the _flag_\n if (symbol.fishKind === 'ARGPARSE' && !symbol.containsPosition(position) && newText?.startsWith('_flag_')) {\n return newText.replace(/^_flag_/g, '').replace(/_/g, '-');\n }\n // EDGE CASE 2: rename on a flag usage: `--values-with`\n // would still work if the rename request is under `argparse 'values-with=?'`\n // So, we need to check for leading '-', and remove them\n if (symbol.fishKind === 'ARGPARSE' && !symbol.containsPosition(position) && newText?.startsWith('-')) {\n return newText.replace(/^-{1,2}/, '');\n }\n return newText;\n}\n\nfunction canRenameWithNewText(analyzer: Analyzer, doc: LspDocument, position: Position, newText: string): boolean {\n const isShort = (str: string) => {\n if (str.startsWith('--')) return false;\n if (str.startsWith('-')) return true;\n return false;\n };\n\n const isLong = (str: string) => {\n if (str.startsWith('--')) return true;\n if (str.startsWith('-')) return false;\n return false;\n };\n\n const isEqualFlags = (str1: string, str2: string) => {\n if (isShort(str1) && !isShort(str2)) {\n return false;\n }\n if (isLong(str1) && !isLong(str2)) {\n return false;\n }\n return true;\n };\n\n const isFlag = (str: string) => {\n return str.startsWith('-');\n };\n\n const oldText = analyzer.wordAtPoint(doc.uri, position.line, position.character);\n logger.log({\n oldText,\n newText,\n });\n if (oldText && isFlag(oldText) && !isEqualFlags(oldText, newText)) return false;\n return true;\n}\n"
},
{
"path": "src/selection-range.ts",
"content": "import { SelectionRange, Position } from 'vscode-languageserver';\nimport { SyntaxNode } from 'web-tree-sitter';\nimport { LspDocument } from './document';\nimport { analyzer } from './analyze';\nimport { isPositionInNode, getRange } from './utils/tree-sitter';\n\n/**\n * Provides smart selection ranges for fish shell code.\n *\n * This allows users to incrementally expand their selection based on the\n * syntactic structure of the code (e.g., word → argument → command → block → function).\n *\n * The selection hierarchy follows the tree-sitter parse tree structure.\n */\n\n/**\n * Find the smallest node containing the position\n */\nfunction findSmallestNode(node: SyntaxNode, position: Position): SyntaxNode | null {\n if (!isPositionInNode(position, node)) {\n return null;\n }\n\n // Try to find a smaller child node\n for (const child of node.namedChildren) {\n const result = findSmallestNode(child, position);\n if (result) {\n return result;\n }\n }\n\n // Skip whitespace and newline nodes for selection\n if (node.type === '\\\\n' || node.type === ' ') {\n return node.parent || node;\n }\n\n return node;\n}\n\n/**\n * Determine if a node type should be included in the selection hierarchy\n */\nfunction shouldIncludeInHierarchy(node: SyntaxNode): boolean {\n // Skip these node types as they don't provide meaningful selection boundaries\n const skipTypes = ['\\\\n', ' ', '(', ')', '[', ']', '{', '}', '\"', \"'\", '$'];\n return !skipTypes.includes(node.type);\n}\n\n/**\n * Build the selection range hierarchy from a node upwards\n */\nfunction buildSelectionHierarchy(node: SyntaxNode): SelectionRange {\n const range = getRange(node);\n\n // Find the next meaningful parent in the hierarchy\n let parent = node.parent;\n let parentRange: SelectionRange | undefined = undefined;\n\n while (parent) {\n // Only include meaningful nodes in the hierarchy\n if (shouldIncludeInHierarchy(parent)) {\n // Avoid creating redundant parent selections with identical ranges\n const parentLspRange = getRange(parent);\n if (\n parentLspRange.start.line !== range.start.line ||\n parentLspRange.start.character !== range.start.character ||\n parentLspRange.end.line !== range.end.line ||\n parentLspRange.end.character !== range.end.character\n ) {\n parentRange = buildSelectionHierarchy(parent);\n break;\n }\n }\n parent = parent.parent;\n }\n\n return {\n range,\n parent: parentRange,\n };\n}\n\n/**\n * Get selection ranges for the given positions in the document\n */\nexport function getSelectionRanges(\n document: LspDocument,\n positions: Position[],\n): SelectionRange[] {\n const result: SelectionRange[] = [];\n\n const rootNode = analyzer.getRootNode(document.uri);\n if (!rootNode) {\n return result;\n }\n\n for (const position of positions) {\n const node = findSmallestNode(rootNode, position);\n if (node) {\n result.push(buildSelectionHierarchy(node));\n }\n }\n\n return result;\n}\n"
},
{
"path": "src/semantic-tokens.ts",
"content": "import { SyntaxNode } from 'web-tree-sitter';\nimport { analyzer, EnsuredAnalyzeDocument } from './analyze';\nimport * as LSP from 'vscode-languageserver';\nimport { logger } from './logger';\nimport { FishSymbol } from './parsing/symbol';\nimport { flattenNested } from './utils/flatten';\nimport { calculateModifiersMask, createTokensFromMatches, getTextMatchPositions, getVariableModifiers, SemanticToken, SemanticTokenModifier, FishSemanticTokens } from './utils/semantics';\nimport { isCommandName, isCommandWithName, isEndStdinCharacter, isShebang, isVariableExpansion } from './utils/node-types';\nimport { LspDocument } from './document';\nimport { BuiltInList } from './utils/builtins';\nimport { isDiagnosticComment } from './diagnostics/comments-handler';\nimport { getRange, isNodeWithinRange } from './utils/tree-sitter';\nimport { getSymbolModifiers } from './parsing/symbol-modifiers';\nimport { PrebuiltDocumentationMap } from './utils/snippets';\nimport { AutoloadedPathVariables } from './utils/process-env';\n\n/**\n * We only want to return the semantic tokens that clients aren't highlighting, since\n * they likely don't use analysis to determine which arguments/words in a script are\n * defining symbols.\n *\n * Cases which we want to return semantic tokens for:\n * - FishSymbol definitions and references:\n * - Function definitions (so that function names can be highlighted differently)\n * - Function calls (so that function calls can be highlighted differently)\n * - Variable definitions (so that variable names can be highlighted differently)\n * - Variable references (so that variable references can be highlighted differently)\n * - Special tokens: `--`\n * - Special comments:\n * - Disable diagnostics comments: `# @fish-lsp-disable ...`\n * - Shebangs: `#!/usr/bin/env fish`\n *\n * We really don't care about modifier support at this time. Since we've already worked\n * pretty significantly to resolve these correctly directly from a FishSymbol, we can\n * determine what/which modifiers to include once more language clients clarify\n * how they would like to handle them.\n */\n\n/**\n * Convert modifier names to bitmask, filtering out unsupported modifiers.\n */\nfunction modifiersToBitmask(modifiers: SemanticTokenModifier[]): number {\n return modifiers.reduce((mask, mod) => {\n const idx = FishSemanticTokens.legend.tokenModifiers.indexOf(mod);\n return idx >= 0 ? mask | 1 << idx : mask;\n }, 0);\n}\n\nfunction symbolToSemanticToken(symbol: FishSymbol): SemanticToken | null {\n if (symbol.isFunction()) {\n // Get modifiers from the symbol using getSymbolModifiers\n // This filters to only supported modifiers (no autoloaded, not-autoloaded, script, etc.)\n const mods = getSymbolModifiers(symbol);\n\n // Highlight alias names as functions (the alias name itself, not the 'alias' keyword)\n // The 'alias' keyword is handled by the keyword handler\n return {\n line: symbol.selectionRange.start.line,\n startChar: symbol.selectionRange.start.character,\n length: symbol.selectionRange.end.character - symbol.selectionRange.start.character,\n tokenType: FishSemanticTokens.types.function,\n tokenModifiers: modifiersToBitmask(mods),\n };\n } else if (symbol.isVariable()) {\n // Use selectionRange which excludes the $ prefix\n const startChar = symbol.selectionRange.start.character;\n const length = symbol.selectionRange.end.character - startChar;\n\n // Skip if the length is invalid (could be shebang or other non-variable symbol)\n if (length <= 0) {\n return null;\n }\n\n // Get modifiers from the symbol\n const mods = getSymbolModifiers(symbol);\n\n return {\n line: symbol.selectionRange.start.line,\n startChar,\n length,\n tokenType: FishSemanticTokens.types.variable,\n tokenModifiers: modifiersToBitmask(mods),\n };\n }\n return null;\n}\n\n/**\n * Structural keywords that modify control flow or define blocks.\n * These are highlighted as keywords, not functions.\n */\nconst STRUCTURAL_KEYWORDS = [\n 'function', 'end',\n 'if', 'else',\n 'for', 'while', 'in',\n 'switch', 'case',\n 'and', 'or', 'not',\n 'break', 'continue', 'return', 'exit',\n 'begin',\n 'alias',\n];\n\n/**\n * Check if a node is a structural keyword.\n * These are block-modifying keywords like `if`, `for`, `function`, etc.\n */\nconst isStructuralKeyword = (n: SyntaxNode): boolean => {\n // Direct node type match (e.g., 'function', 'end', 'in')\n if (STRUCTURAL_KEYWORDS.includes(n.type)) {\n return true;\n }\n\n // For command nodes, check the command name\n if (n.type === 'command' || isCommandName(n)) {\n const cmdName = n.type === 'command' && n.firstNamedChild\n ? n.firstNamedChild.text\n : n.text;\n return STRUCTURAL_KEYWORDS.includes(cmdName);\n }\n\n return false;\n};\n\n/**\n * Check if a command is a builtin function (not a structural keyword).\n * These are commands from `builtin -n` that aren't structural keywords.\n * Examples: echo, set, path, source, fish_key_reader\n */\nconst isBuiltinFunction = (n: SyntaxNode): boolean => {\n if (n.type !== 'command') return false;\n\n const cmdName = n.firstNamedChild;\n if (!cmdName) return false;\n\n // Must be in builtin list and NOT a structural keyword\n return BuiltInList.includes(cmdName.text) && !STRUCTURAL_KEYWORDS.includes(cmdName.text);\n};\n\n/**\n * Check if a command is a user-defined or fish-shipped function call.\n * Excludes structural keywords and builtin functions.\n */\nconst isUserFunction = (n: SyntaxNode): boolean => {\n if (n.type !== 'command') return false;\n if (isStructuralKeyword(n)) return false;\n if (isBuiltinFunction(n)) return false;\n if (isCommandWithName(n, '[')) return false; // Special handling for bracket test\n return true;\n};\n\nconst isBracketTestCommand = (n: SyntaxNode) => isCommandWithName(n, '[');\n\ntype isNodeMatch = (node: SyntaxNode) => boolean;\ntype nodeToTokenFunc = (node: SyntaxNode, ctx: SemanticTokenContext) => void;\ntype NodeToToken = [isNodeMatch, nodeToTokenFunc];\n\nconst nodeToTokenHandler: NodeToToken[] = [\n // `#!/usr/bin/env fish`\n [isShebang, (n, ctx) => {\n ctx.tokens.push(\n SemanticToken.fromNode(n, FishSemanticTokens.types.decorator, 0),\n );\n }],\n\n // `# @fish-lsp-disable ...` - only highlight the @fish-lsp-* part\n [isDiagnosticComment, (n, ctx) => {\n ctx.tokens.push(\n ...createTokensFromMatches(\n getTextMatchPositions(n, /@fish-lsp-(enable|disable)(?:-next-line)?/g),\n FishSemanticTokens.types.keyword,\n 0,\n ),\n );\n }],\n\n // Special handling for `[` test command - highlight opening [ and closing ]\n // Example: [ -f /tmp/foo.fish ] or [ -n \"string\" ]\n // This ensures we don't confuse it with array indexing like $arr[0]\n [isBracketTestCommand, (n, ctx) => {\n const firstChild = n.firstNamedChild;\n if (firstChild && firstChild.type === 'word') {\n // Find the opening [ token within the word node\n const openBracket = firstChild.firstChild;\n if (openBracket && openBracket.type === '[') {\n ctx.tokens.push(\n SemanticToken.fromNode(openBracket, FishSemanticTokens.types.function, calculateModifiersMask('defaultLibrary')),\n );\n }\n }\n\n // Find the closing ] in the last argument\n const lastChild = n.lastNamedChild;\n if (lastChild && lastChild.type === 'word') {\n const closeBracket = lastChild.firstChild;\n if (closeBracket && closeBracket.type === ']') {\n ctx.tokens.push(\n SemanticToken.fromNode(closeBracket, FishSemanticTokens.types.function, calculateModifiersMask('defaultLibrary')),\n );\n }\n }\n }],\n\n // Structural keywords: `if`, `for`, `function`, `alias`, etc.\n [isStructuralKeyword, (n, ctx) => {\n // For command nodes, only highlight the first child (the keyword itself)\n // For non-command nodes (like standalone keywords), highlight the whole node\n const targetNode = n.type === 'command' && n.firstNamedChild ? n.firstNamedChild : n;\n ctx.tokens.push(\n SemanticToken.fromNode(targetNode, FishSemanticTokens.types.keyword, 0),\n );\n }],\n\n // Builtin functions: `echo`, `set`, `path`, `source`, etc.\n // These are commands from `builtin -n` but not structural keywords\n //\n // As of PR #133, builtin functions are now treated exactly the same\n // as defaultLibrary functions which include shared function definitions\n // like: `__fish_use_subcommand` or other `$__fish_data_dir/functions/*.fish` files\n [isBuiltinFunction, (n, ctx) => {\n const cmd = n.firstNamedChild;\n if (!cmd) return;\n ctx.tokens.push(\n SemanticToken.fromNode(cmd, FishSemanticTokens.types.function, calculateModifiersMask('defaultLibrary')),\n );\n }],\n\n // User-defined or fish-shipped function calls\n [isUserFunction, (n, ctx) => {\n const cmd = n.firstNamedChild;\n if (!cmd) return;\n\n // Look up the function symbol to get its modifiers\n let modifiers = 0;\n const localSymbols = analyzer.cache.getFlatDocumentSymbols(ctx.document.uri);\n const funcSymbol = localSymbols.find(s => s.isFunction() && s.name === cmd.text);\n\n if (funcSymbol) {\n // Use getSymbolModifiers and filter to supported modifiers\n const mods = getSymbolModifiers(funcSymbol).filter(m =>\n FishSemanticTokens.legend.tokenModifiers.includes(m as any),\n );\n modifiers = modifiersToBitmask(mods);\n } else {\n // Check global symbols\n const globalSymbols = analyzer.globalSymbols.find(cmd.text);\n const globalFunc = globalSymbols.find(s => s.isFunction());\n if (globalFunc) {\n const mods = getSymbolModifiers(globalFunc).filter(m =>\n FishSemanticTokens.legend.tokenModifiers.includes(m as any),\n );\n modifiers = modifiersToBitmask(mods);\n } else {\n // Check if it's a fish-shipped function\n const fishShippedDocs = PrebuiltDocumentationMap.getByName(cmd.text);\n const isFishShipped = fishShippedDocs.some(doc => doc.type === 'function');\n if (isFishShipped) {\n modifiers = calculateModifiersMask('defaultLibrary');\n } else {\n // Last resort: check if this could be an autoloaded function\n // by searching fish_function_path directories\n const autoloadedPath = AutoloadedPathVariables.findAutoloadedFunctionPath(cmd.text);\n if (autoloadedPath) {\n modifiers = calculateModifiersMask('global');\n }\n }\n }\n }\n\n ctx.tokens.push(\n SemanticToken.fromNode(cmd, FishSemanticTokens.types.function, modifiers),\n );\n }],\n\n // variable expansions\n [isVariableExpansion, (n, ctx) => {\n const variableName = n.text.replace(/^\\$/, '');\n const modifiers = getVariableModifiers(variableName, ctx.document.uri);\n\n ctx.tokens.push(\n ...createTokensFromMatches(\n getTextMatchPositions(n, /[^$]+/),\n FishSemanticTokens.types.variable,\n modifiers,\n ),\n );\n }],\n\n // special end-of-stdin character `--`\n [isEndStdinCharacter, (n, ctx) => {\n ctx.tokens.push(\n SemanticToken.fromNode(n, FishSemanticTokens.types.operator, 0),\n );\n }],\n\n // number literals: integers and floats\n [(n) => n.type === 'integer' || n.type === 'float', (n, ctx) => {\n ctx.tokens.push(\n SemanticToken.fromNode(n, FishSemanticTokens.types.number, 0),\n );\n }],\n\n];\n\nexport function getSemanticTokensSimplest(analyzedDoc: EnsuredAnalyzeDocument, range: LSP.Range) {\n const nodes = analyzer.getNodes(analyzedDoc.document.uri);\n const symbols = flattenNested(...analyzedDoc.documentSymbols);\n\n // create hashmap of semantic tokens? or something for O(1)ish lookups so that other\n // types of tokens that we create can immediately be skipped if they already exist.\n\n const ctx: SemanticTokenContext = SemanticTokenContext.create({ document: analyzedDoc.document });\n\n for (const symbol of symbols) {\n if (!symbol.focusedNode) continue;\n if (range && !isNodeWithinRange(symbol.focusedNode, range)) continue;\n\n const token = symbolToSemanticToken(symbol);\n if (token) {\n ctx.add(token);\n }\n }\n\n // now we're just about done!\n for (const node of nodes) {\n // out of range\n if (!isNodeWithinRange(node, range)) {\n continue;\n }\n\n // filter out dupes\n if (ctx.hasNode(node)) {\n continue;\n }\n // ^^^ consider avoiding this till the end to limit runtime complexity? ^^^\n\n nodeToTokenHandler.find(([isMatch, toToken]) => {\n if (isMatch(node)) {\n toToken(node, ctx);\n return true; // Stop searching once we find a match\n }\n return false;\n });\n }\n\n return ctx.build();\n}\n\nconst hashToken = (token: SemanticToken): string => {\n return `${token.line}:${token.startChar}:${token.tokenType}`;\n};\n\nclass SemanticTokenContext {\n private constructor(\n public document: LspDocument,\n public tokens: SemanticToken[] = [],\n private seenTokens: Map = new Map(),\n ) { }\n\n public static create({ document, tokens = [] }: {\n document: LspDocument;\n tokens?: SemanticToken[];\n }): SemanticTokenContext {\n return new SemanticTokenContext(document, tokens);\n }\n\n public has(token: SemanticToken): boolean {\n return this.seenTokens.has(hashToken(token));\n }\n public hasNode(node: SyntaxNode): boolean {\n const token = SemanticToken.fromNode(node, 0, 0);\n return this.seenTokens.has(hashToken(token));\n }\n\n public add(...tokens: SemanticToken[]): void {\n for (const token of tokens) {\n if (!this.seenTokens.has(hashToken(token))) {\n this.seenTokens.set(hashToken(token), token);\n this.tokens.push(token);\n }\n }\n }\n\n public get size(): number {\n return this.tokens.length;\n }\n\n public getTokens(): SemanticToken[] {\n return this.tokens;\n }\n\n public clear(): void {\n this.tokens.length = 0;\n this.seenTokens.clear();\n this.tokens = [];\n }\n\n public show(): void {\n logger.log({\n document: this.document?.uri,\n size: this.size,\n tokens: this.tokens,\n seenTokens: Array.from(this.seenTokens.values()),\n });\n }\n\n public build() {\n const builder = new LSP.SemanticTokensBuilder();\n\n // Sort tokens by position\n const sortedTokens = [...this.tokens].sort((a, b) => {\n if (a.line !== b.line) return a.line - b.line;\n if (a.startChar !== b.startChar) return a.startChar - b.startChar;\n return a.length - b.length;\n });\n\n // Remove duplicates and overlaps (keep first occurrence)\n const uniqueTokens: SemanticToken[] = [];\n let lastEnd = { line: -1, char: -1 };\n\n for (const token of sortedTokens) {\n const tokenEnd = token.startChar + token.length;\n\n // Skip if this token overlaps with the previous one on the same line\n if (token.line === lastEnd.line && token.startChar < lastEnd.char) {\n continue;\n }\n\n uniqueTokens.push(token);\n lastEnd = { line: token.line, char: tokenEnd };\n }\n\n // Push tokens to builder\n for (const token of uniqueTokens) {\n builder.push(\n token.line,\n token.startChar,\n token.length,\n token.tokenType,\n token.tokenModifiers,\n );\n }\n\n return builder.build();\n }\n}\n\ntype SemanticTokensParams = LSP.SemanticTokensParams | LSP.SemanticTokensRangeParams;\n/**\n * Type guards for distinguishing between full and range semantic token requests.\n */\nexport namespace Semantics {\n export const params = {\n isFull(params: SemanticTokensParams): params is LSP.SemanticTokensParams {\n return (\n (params as LSP.SemanticTokensParams).textDocument !== undefined &&\n (params as LSP.SemanticTokensRangeParams).range === undefined\n );\n },\n isRange(params: SemanticTokensParams): params is LSP.SemanticTokensRangeParams {\n return (params as LSP.SemanticTokensRangeParams).range !== undefined;\n },\n };\n export const response = {\n empty: (): LSP.SemanticTokens => ({ data: [] }),\n };\n}\n\n/**\n * Main handler for semantic token requests.\n */\nexport function semanticTokenHandler(params: SemanticTokensParams): LSP.SemanticTokens {\n // retrieve the analyzed document for the requested URI\n const cachedDoc = analyzer.cache.getDocument(params.textDocument.uri)?.ensureParsed();\n if (!cachedDoc) {\n logger.warning(`No analyzed document found for URI: ${params.textDocument.uri}`);\n return Semantics.response.empty();\n }\n\n /* handle our 2 use cases */\n\n if (Semantics.params.isRange(params)) {\n return getSemanticTokensSimplest(cachedDoc, params.range);\n } else if (Semantics.params.isFull(params)) {\n return getSemanticTokensSimplest(cachedDoc, getRange(cachedDoc.root));\n }\n\n return Semantics.response.empty();\n}\n"
},
{
"path": "src/server.ts",
"content": "// Import polyfills for Node.js 18 compatibility\nimport './utils/polyfills';\n// Initialize virtual filesystem (must be before any embedded asset usage)\nimport './virtual-fs';\nimport { SyntaxNode } from 'web-tree-sitter';\nimport { analyzer, Analyzer } from './analyze';\nimport { InitializeParams, CompletionParams, Connection, CompletionList, CompletionItem, MarkupContent, DocumentSymbolParams, DefinitionParams, Location, ReferenceParams, DocumentSymbol, InitializeResult, HoverParams, Hover, RenameParams, TextDocumentPositionParams, TextDocumentIdentifier, WorkspaceEdit, TextEdit, DocumentFormattingParams, DocumentRangeFormattingParams, FoldingRangeParams, FoldingRange, InlayHintParams, MarkupKind, WorkspaceSymbolParams, WorkspaceSymbol, SymbolKind, CompletionTriggerKind, SignatureHelpParams, SignatureHelp, ImplementationParams, CodeLensParams, CodeLens, WorkspaceFoldersChangeEvent, SelectionRangeParams, SelectionRange } from 'vscode-languageserver';\nimport * as LSP from 'vscode-languageserver';\nimport { LspDocument, documents, rangeOverlapsLineSpan } from './document';\nimport { formatDocumentWithIndentComments, formatDocumentContent } from './formatting';\nimport { logger, now } from './logger';\nimport { connection, setExternalConnection } from './utils/startup';\nimport { formatTextWithIndents, symbolKindsFromNode, uriToPath } from './utils/translation';\nimport { getChildNodes } from './utils/tree-sitter';\nimport { getVariableExpansionDocs, handleHover } from './hover';\nimport { DocumentationCache, initializeDocumentationCache } from './utils/documentation-cache';\nimport { getWorkspacePathsFromInitializationParams, initializeDefaultFishWorkspaces } from './utils/workspace';\nimport { workspaceManager } from './utils/workspace-manager';\nimport { formatFishSymbolTree, filterLastPerScopeSymbol, FishSymbol } from './parsing/symbol';\nimport { CompletionPager, initializeCompletionPager, isInVariableExpansionContext, SetupData } from './utils/completion/pager';\nimport { FishCompletionItem } from './utils/completion/types';\nimport { getDocumentationResolver } from './utils/completion/documentation';\nimport { FishCompletionList } from './utils/completion/list';\nimport { PrebuiltDocumentationMap, getPrebuiltDocUrl } from './utils/snippets';\nimport { findParent, findParentCommand, isAliasDefinitionName, isBraceExpansion, isCommand, isCommandName, isConcatenatedValue, isConcatenation, isEndStdinCharacter, isOption, isPathNode, isReturnStatusNumber, isVariableDefinition } from './utils/node-types';\nimport { config, Config } from './config';\nimport { enrichToMarkdown, handleBraceExpansionHover, handleEndStdinHover, handleSourceArgumentHover } from './documentation';\nimport { findActiveParameterStringRegex, getAliasedCompletionItemSignature, getDefaultSignatures, getFunctionSignatureHelp, isRegexStringSignature } from './signature';\nimport { CompletionItemMap } from './utils/completion/startup-cache';\nimport { getDocumentHighlights } from './document-highlight';\nimport { semanticTokenHandler } from './semantic-tokens';\nimport { buildCommentCompletions } from './utils/completion/comment-completions';\nimport { codeActionHandlers } from './code-actions/code-action-handler';\nimport { createExecuteCommandHandler } from './command';\nimport { getAllInlayHints } from './inlay-hints';\nimport { setupProcessEnvExecFile } from './utils/process-env';\nimport { flattenNested } from './utils/flatten';\nimport { isArgparseVariableDefinitionName } from './parsing/argparse';\nimport { isSourceCommandArgumentName } from './parsing/source';\nimport { getReferences } from './references';\nimport { getRenames } from './renames';\nimport { getReferenceCountCodeLenses } from './code-lens';\nimport { getSelectionRanges } from './selection-range';\nimport { PkgJson } from './utils/commander-cli-subcommands';\nimport { ProgressNotification } from './utils/progress-notification';\nimport { md } from './utils/markdown-builder';\n\nexport type SupportedFeatures = {\n codeActionDisabledSupport: boolean;\n};\n\nexport let server: FishServer;\n\n/**\n * The globally accessible configuration setting. Set from the client, and used by the server.\n * When enabled, the analyzer will search through the current workspace, and update it's\n * cache of symbols only within the current workspace. When disabled, the analyzer will have\n * to search through all workspaces.\n *\n * Also, this setting is used to determine if the initializationResult.workspace.workspaceFolders\n * should be enabled or disabled.\n */\nexport let hasWorkspaceFolderCapability = false;\nexport const enableWorkspaceFolderSupport = () => {\n hasWorkspaceFolderCapability = true;\n};\n\nexport let currentDocument: LspDocument | null = null;\n\nexport let cachedDocumentation: DocumentationCache;\nexport let cachedCompletionMap: CompletionItemMap;\n\nexport default class FishServer {\n /**\n * How a client importing the server as a module would connect to a new server instance\n *\n * After a connection is created by the client this method will setup the server\n * to allow the connection to communicate between the client and server.\n * ___\n *\n * @example\n * ```ts\n * import FishServer from 'fish-lsp';\n * import {\n * createConnection,\n * InitializeParams,\n * InitializeResult,\n * ProposedFeatures,\n * } from 'vscode-languageserver/node';\n *\n * const connection = createConnection(ProposedFeatures.all)\n *\n * connection.onInitialize(\n * async (params: InitializeParams): Promise => {\n * const { initializeResult } = await FishServer.create(connection, params);\n *\n * return initializeResult;\n * },\n * );\n * connection.listen();\n * ```\n * ___\n *\n * @param connection The LSP.Connection to use\n * @param params The initialization parameters from the client\n * @returns The created FishServer instance and the initialization result\n */\n public static async create(\n connection: Connection,\n params: InitializeParams,\n ): Promise<{ server: FishServer; initializeResult: InitializeResult; }> {\n setExternalConnection(connection);\n await setupProcessEnvExecFile();\n const capabilities = params.capabilities;\n const initializeResult = Config.initialize(params, connection);\n logger.log({\n server: 'FishServer',\n rootUri: params.rootUri,\n rootPath: params.rootPath,\n workspaceFolders: params.workspaceFolders,\n });\n\n // set this only it it hasn't been set yet\n hasWorkspaceFolderCapability = !!(\n !!capabilities?.workspace && !!capabilities?.workspace.workspaceFolders\n );\n logger.debug('hasWorkspaceFolderCapability', hasWorkspaceFolderCapability);\n\n const initializeUris = getWorkspacePathsFromInitializationParams(params);\n logger.info('initializeUris', initializeUris);\n\n // Run these operations in parallel rather than sequentially\n const [\n cache,\n _workspaces,\n completionsMap,\n ] = await Promise.all([\n initializeDocumentationCache(),\n initializeDefaultFishWorkspaces(...initializeUris),\n CompletionItemMap.initialize(),\n ]);\n\n cachedDocumentation = cache;\n cachedCompletionMap = completionsMap;\n\n await Analyzer.initialize();\n\n const completions = await initializeCompletionPager(logger, completionsMap);\n\n server = new FishServer(\n completions,\n completionsMap,\n cache,\n params,\n );\n server.register(connection);\n return { server, initializeResult };\n }\n\n protected features: SupportedFeatures;\n public clientSupportsShowDocument: boolean;\n public backgroundAnalysisComplete: boolean;\n private backgroundAnalysisInProgress: boolean;\n\n constructor(\n private completion: CompletionPager,\n private completionMap: CompletionItemMap,\n private documentationCache: DocumentationCache,\n private initializeParams: InitializeParams,\n\n ) {\n this.features = { codeActionDisabledSupport: true };\n this.clientSupportsShowDocument = false;\n this.backgroundAnalysisComplete = false;\n this.backgroundAnalysisInProgress = false;\n }\n\n /**\n * Bind the connection handlers to their corresponding methods in the\n * server so that {@link FishServer.create()} initializes the server with all handlers\n * enabled.\n *\n * The `src/config.ts` file handles dynamic enabling/disabling of these\n * handlers based on client capabilities and user configuration.\n *\n * @see {@link Config.getResultCapabilities} for the capabilities negotiated\n *\n * @param connection The {@link https://github.com/microsoft/vscode-extension-samples/blob/5839b5c2336e1488ee642a037a2084f2dd3d6755/lsp-embedded-language-service/server/src/server.ts#L20|LSP.Connection} to register handlers on\n * @returns void\n */\n register(connection: Connection): void {\n // setup callback handlers\n const { onCodeActionCallback, onCodeActionResolveCallback } = codeActionHandlers();\n const documentHighlightHandler = getDocumentHighlights(analyzer);\n // Semantic tokens handler using simplified unified handler\n // The semanticTokenHandler handles both full document and range requests internally\n const commandCallback = createExecuteCommandHandler(connection);\n\n // register the handlers\n // connection.onDidOpenTextDocument(this.didOpenTextDocument.bind(this));\n // connection.onDidChangeTextDocument(this.didChangeTextDocument.bind(this));\n // connection.onDidCloseTextDocument(this.didCloseTextDocument.bind(this));\n connection.onDidSaveTextDocument(this.didSaveTextDocument.bind(this));\n\n connection.onCompletion(this.onCompletion.bind(this));\n connection.onCompletionResolve(this.onCompletionResolve.bind(this));\n\n connection.onDocumentSymbol(this.onDocumentSymbols.bind(this));\n connection.onWorkspaceSymbol(this.onWorkspaceSymbol.bind(this));\n connection.onWorkspaceSymbolResolve(this.onWorkspaceSymbolResolve.bind(this));\n\n connection.onDefinition(this.onDefinition.bind(this));\n connection.onImplementation(this.onImplementation.bind(this));\n connection.onReferences(this.onReferences.bind(this));\n connection.onHover(this.onHover.bind(this));\n\n connection.onRenameRequest(this.onRename.bind(this));\n\n connection.onDocumentFormatting(this.onDocumentFormatting.bind(this));\n connection.onDocumentRangeFormatting(this.onDocumentRangeFormatting.bind(this));\n connection.onDocumentOnTypeFormatting(this.onDocumentTypeFormatting.bind(this));\n connection.onCodeAction(onCodeActionCallback);\n connection.onCodeActionResolve(onCodeActionResolveCallback);\n\n connection.onCodeLens(this.onCodeLens.bind(this));\n connection.onFoldingRanges(this.onFoldingRanges.bind(this));\n connection.onSelectionRanges(this.onSelectionRanges.bind(this));\n\n connection.onDocumentHighlight(documentHighlightHandler);\n connection.languages.inlayHint.on(this.onInlayHints.bind(this));\n connection.languages.semanticTokens.on(semanticTokenHandler);\n connection.languages.semanticTokens.onRange(semanticTokenHandler);\n\n connection.onSignatureHelp(this.onShowSignatureHelp.bind(this));\n connection.onExecuteCommand(commandCallback);\n\n connection.onInitialized(this.onInitialized.bind(this));\n connection.onShutdown(this.onShutdown.bind(this));\n documents.listen(connection);\n\n documents.onDidOpen(async ({ document }) => {\n this.logDocument('documents.onDidOpen', document);\n\n const { uri } = this.analyzeDocument(document);\n\n if (workspaceManager.needsAnalysis() && !this.backgroundAnalysisInProgress) {\n logger.info('didOpenTextDocument: Starting workspace analysis with progress');\n const progress = await ProgressNotification.create('didOpenTextDocument');\n const allDocs = workspaceManager.allAnalysisDocuments().length;\n progress.begin(`[fish-lsp] analyzing ${allDocs} documents`, 0, 'open', true);\n await workspaceManager.analyzePendingDocuments(progress, (str) => logger.info('didOpen', str));\n progress.done();\n } else if (this.backgroundAnalysisInProgress) {\n logger.info('didOpenTextDocument: Skipping analysis - background analysis already in progress');\n }\n if (this.backgroundAnalysisComplete) {\n analyzer.diagnostics.requestUpdate(uri, true); // full diagnostics pass on open\n }\n });\n\n documents.onDidChangeContent(({ document }) => {\n this.logDocument('documents.onDidChangeContent', document, {\n showDiagnostics: true,\n showLastChangedSpan: true,\n });\n\n const { uri } = this.analyzeDocument(document);\n const diagnostics = analyzer.diagnostics.get(uri) || [];\n const changeSpan = document.lastChangedLineSpan;\n const overlapExists =\n !changeSpan\n ? true\n : diagnostics?.some(d => rangeOverlapsLineSpan(d.range, changeSpan));\n\n // Get the first changed line for overlap detection\n analyzer.diagnostics.requestUpdate(uri, overlapExists, changeSpan);\n });\n\n documents.onDidClose(({ document }) => {\n this.logDocument('documents.onDidClose', document);\n const { uri } = document;\n workspaceManager.handleCloseDocument(uri);\n analyzer.diagnostics.delete(uri);\n analyzer.removeDocumentSymbols(uri);\n });\n\n logger.log({ 'server.register': 'registered' });\n }\n\n async didSaveTextDocument(params: LSP.DidSaveTextDocumentParams): Promise {\n this.logParams('server.didSaveTextDocument', params);\n const document = documents.get(params.textDocument.uri);\n\n if (!document) return;\n\n const { uri } = this.analyzeDocument(document);\n\n await workspaceManager.analyzePendingDocuments();\n analyzer.diagnostics.requestUpdate(uri, true); // immediate on save\n this.logDocument('didSaveDocument', document, { showDiagnostics: true, showLastChangedSpan: true });\n }\n\n /**\n * Stop the server and close all workspaces.\n */\n async onShutdown() {\n analyzer.diagnostics.clear();\n workspaceManager.clear();\n currentDocument = null;\n for (const doc of documents.all()) {\n connection.sendDiagnostics({ uri: doc.uri, diagnostics: [] });\n }\n // this.diagnosticsWorker.dispose();\n this.backgroundAnalysisComplete = false;\n this.backgroundAnalysisInProgress = false;\n }\n\n /**\n * Called after the server.onInitialize() handler, dynamically registers\n * the onDidChangeWorkspaceFolders handler if the client supports it.\n * It will also try to analyze the current workspaces' pending documents.\n */\n async onInitialized(params: any): Promise<{\n totalDocuments: number;\n items: { [path: string]: string[]; };\n counts: { [path: string]: number; };\n }> {\n const supportsProgress = this.initializeParams.capabilities.window?.workDoneProgress;\n logger.log(`Progress support: ${supportsProgress}`);\n logger.log('onInitialized', params);\n logger.log('onInitialized fired');\n logger.info('SERVER INITIALIZED', {\n buildPath: PkgJson.path,\n buildVersion: PkgJson.version,\n buildTime: PkgJson.buildTime,\n executedAt: now(),\n });\n if (hasWorkspaceFolderCapability) {\n try {\n connection.workspace.onDidChangeWorkspaceFolders(event => {\n logger.info({\n 'connection.workspace.onDidChangeWorkspaceFolders': 'analyzer.onInitialized',\n added: event.added.map(folder => folder.name),\n removed: event.removed.map(folder => folder.name),\n hasWorkspaceFolderCapability: hasWorkspaceFolderCapability,\n });\n this.handleWorkspaceFolderChanges(event);\n });\n } catch (_) {\n // Connection doesn't support workspace folder changes (e.g., in test/diagnostic modes)\n logger.debug('Workspace folder change events not supported by this connection');\n }\n }\n\n let totalDocuments = 0;\n let items: { [path: string]: string[]; } = {};\n const counts: { [path: string]: number; } = {};\n try {\n // Set flag BEFORE creating progress to prevent interference\n this.backgroundAnalysisInProgress = true;\n logger.info('Starting background analysis in onInitialized');\n\n const progress = await ProgressNotification.create('onInitialized');\n logger.log('Progress created');\n\n // Begin progress immediately\n progress.begin('[fish-lsp] analyzing workspaces', 0);\n\n if (currentDocument) {\n logger.info('Re-analyzing current document after background analysis', { uri: currentDocument.uri });\n workspaceManager.current?.addPending(...analyzer.collectAllSources(currentDocument.uri));\n }\n\n const result = await workspaceManager.analyzePendingDocuments(progress, (str) => logger.info('onInitialized', str));\n totalDocuments = result.totalDocuments;\n items = result.items;\n Object.entries(items).forEach(([key, value]) => {\n counts[key] = value.length;\n });\n\n progress.done();\n this.backgroundAnalysisComplete = true;\n this.backgroundAnalysisInProgress = false;\n logger.info('Background analysis complete');\n if (currentDocument) {\n this.analyzeDocument(currentDocument);\n analyzer.diagnostics.requestUpdate(currentDocument.uri, true); // full diagnostics pass after analysis\n }\n } catch (error) {\n this.backgroundAnalysisInProgress = false;\n this.backgroundAnalysisComplete = false;\n logger.error('Error during background analysis onInitialized', error);\n }\n\n logger.info(`Initial analysis complete. Analyzed ${totalDocuments} documents.`);\n return {\n totalDocuments,\n items,\n counts,\n };\n }\n\n private async handleWorkspaceFolderChanges(event: WorkspaceFoldersChangeEvent) {\n this.logParams('handleWorkspaceFolderChanges', event);\n // Show progress for added workspaces\n const progress = await ProgressNotification.create('handleWorkspaceFolderChanges');\n progress.begin(`[fish-lsp] analyzing workspaces [${event.added.map(s => s.name).join(',')}] added`);\n workspaceManager.handleWorkspaceChangeEvent(event, progress);\n workspaceManager.analyzePendingDocuments(progress);\n progress.done();\n }\n\n onCommand(params: LSP.ExecuteCommandParams): Promise {\n const callback = createExecuteCommandHandler(connection);\n return callback(params);\n }\n\n // @TODO: REFACTOR THIS OUT OF SERVER\n // https://github.com/Dart-Code/Dart-Code/blob/7df6509870d51cc99a90cf220715f4f97c681bbf/src/providers/dart_completion_item_provider.ts#L197-202\n // https://github.com/microsoft/vscode-languageserver-node/pull/322\n // https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#insertTextModehttps://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#insertTextMode\n // • clean up into completion.ts file & Decompose to state machine, with a function that gets the state machine in this class.\n // DART is best example i've seen for this.\n // ~ https://github.com/Dart-Code/Dart-Code/blob/7df6509870d51cc99a90cf220715f4f97c681bbf/src/providers/dart_completion_item_provider.ts#L197-202 ~\n // • Implement both escapedCompletion script and dump syntax tree script\n // • Add default CompletionLists to complete.ts\n // • Add local file items.\n // • Lastly add parameterInformation items. [ 1477 : ParameterInformation ]\n // convert to CompletionItem[]\n async onCompletion(params: CompletionParams): Promise {\n this.logParams('onCompletion', params);\n if (!this.backgroundAnalysisComplete) {\n return await this.completion.completeEmpty([]);\n }\n\n const { doc, path, current } = this.getDefaults(params);\n let list: FishCompletionList = FishCompletionList.empty();\n\n if (!path || !doc) {\n logger.logAsJson('onComplete got [NOT FOUND]: ' + path);\n return this.completion.empty();\n }\n const symbols = analyzer.allSymbolsAccessibleAtPosition(doc, params.position);\n const { line, word } = analyzer.parseCurrentLine(doc, params.position);\n // logger.log({\n // symbols: symbols.map(s => s.name),\n // });\n\n if (!line) return await this.completion.completeEmpty(symbols);\n\n const fishCompletionData = {\n uri: doc.uri,\n position: params.position,\n context: {\n triggerKind: params.context?.triggerKind || CompletionTriggerKind.Invoked,\n triggerCharacter: params.context?.triggerCharacter,\n },\n } as SetupData;\n\n try {\n if (line.trim().startsWith('#') && current) {\n logger.log('completeComment');\n return buildCommentCompletions(line, params.position, current, fishCompletionData, word);\n }\n if (isInVariableExpansionContext(doc, params.position, line, word, current ?? null)) {\n logger.log('completeVariables');\n return this.completion.completeVariables(line, word, fishCompletionData, symbols);\n }\n } catch (error) {\n logger.warning('ERROR: onComplete ' + error?.toString() || 'error');\n }\n\n try {\n logger.log('complete');\n list = await this.completion.complete(line, fishCompletionData, symbols);\n } catch (error) {\n logger.logAsJson('ERROR: onComplete ' + error?.toString() || 'error');\n }\n return list;\n }\n\n /**\n * until further reworking, onCompletionResolve requires that when a completionBuilderItem() is .build()\n * it it also given the method .kind(FishCompletionItemKind) to set the kind of the item.\n * Not seeing a completion result, with typed correctly is likely caused from this.\n */\n async onCompletionResolve(item: CompletionItem): Promise {\n const fishItem = item as FishCompletionItem;\n logger.log({ onCompletionResolve: fishItem });\n try {\n if (fishItem.useDocAsDetail || fishItem.local) {\n item.documentation = {\n kind: MarkupKind.Markdown,\n value: fishItem.documentation.toString(),\n };\n return item;\n }\n const doc = await getDocumentationResolver(fishItem);\n if (doc) {\n item.documentation = doc as MarkupContent;\n }\n } catch (err) {\n logger.error('onCompletionResolve', err);\n }\n return item;\n }\n\n // • lsp-spec: https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#workspace_symbol\n // • hierarchy of symbols support on line 554: https://github.com/typescript-language-server/typescript-language-server/blob/114d4309cb1450585f991604118d3eff3690237c/src/lsp-server.ts#L554\n //\n // ResolveWorkspaceResult\n // https://github.com/Dart-Code/Dart-Code/blob/master/src/extension/providers/dart_workspace_symbol_provider.ts#L7\n //\n onDocumentSymbols(params: DocumentSymbolParams): DocumentSymbol[] {\n this.logParams('onDocumentSymbols', params);\n\n const { doc } = this.getDefaultsForPartialParams(params);\n if (!doc) return [];\n\n // Get local document symbols\n const localSymbols = analyzer.cache.getDocumentSymbols(doc.uri);\n\n // Get sourced symbols and convert them to nested structure if needed\n const sourcedSymbols = analyzer.collectSourcedSymbols(doc.uri);\n\n // Combine local and sourced symbols and cache the sourced symbols as global definitions\n // local to the document inside the analyzer workspace. Heuristic to cache global symbols\n // more frequently in background analysis of focused document because server.onDocumentSymbols\n // is requested repeatedly in most clients when moving around a LspDocument.\n [...localSymbols, ...sourcedSymbols]\n .filter(s => s.isGlobal() || s.isRootLevel())\n .forEach(s => analyzer.globalSymbols.add(s));\n\n return filterLastPerScopeSymbol(localSymbols)\n .map(s => s.toDocumentSymbol())\n .filter(s => !!s);\n }\n\n public get supportHierarchicalDocumentSymbol(): boolean {\n const textDocument = this.initializeParams?.capabilities.textDocument;\n const documentSymbol = textDocument && textDocument.documentSymbol;\n return (\n !!documentSymbol &&\n !!documentSymbol.hierarchicalDocumentSymbolSupport\n );\n }\n\n async onWorkspaceSymbol(params: WorkspaceSymbolParams): Promise {\n this.logParams('onWorkspaceSymbol', params.query);\n\n const symbols: FishSymbol[] = [];\n const workspace = workspaceManager.current;\n for (const uri of workspace?.allUris || []) {\n const newSymbols = [\n ...analyzer.cache.getDocumentSymbols(uri),\n ...analyzer.collectSourcedSymbols(uri),\n ];\n symbols.push(...filterLastPerScopeSymbol(newSymbols));\n }\n\n logger.log('symbols', {\n uris: workspace?.allUris,\n symbols: symbols.map(s => s.name),\n });\n return analyzer.getWorkspaceSymbols(params.query) || [];\n }\n\n /**\n * Resolve a workspace symbol to its full definition.\n */\n async onWorkspaceSymbolResolve(symbol: WorkspaceSymbol): Promise {\n this.logParams('onWorkspaceSymbolResolve', symbol);\n const { uri } = symbol.location;\n const foundSymbol = analyzer.getFlatDocumentSymbols(uri)\n .find(s => s.name === symbol.name && s.isGlobal());\n if (foundSymbol) {\n return {\n ...foundSymbol.toWorkspaceSymbol(),\n ...foundSymbol.toDocumentSymbol(),\n };\n }\n // This is a no-op, as we don't have any additional information to resolve.\n // In the future, we could add more information to the symbol if needed.\n return symbol;\n }\n\n // https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#showDocumentParams\n async onDefinition(params: DefinitionParams): Promise {\n this.logParams('onDefinition', params);\n\n const { doc } = this.getDefaults(params);\n if (!doc) return [];\n\n const newDefs = analyzer.getDefinitionLocation(doc, params.position);\n for (const location of newDefs) {\n workspaceManager.handleOpenDocument(location.uri);\n workspaceManager.handleUpdateDocument(location.uri);\n }\n if (workspaceManager.needsAnalysis()) {\n await workspaceManager.analyzePendingDocuments();\n }\n return newDefs;\n }\n\n async onReferences(params: ReferenceParams): Promise {\n this.logParams('onReference', params);\n\n const { doc } = this.getDefaults(params);\n if (!doc) return [];\n\n const progress = await connection.window.createWorkDoneProgress();\n\n const defSymbol = analyzer.getDefinition(doc, params.position);\n if (!defSymbol) {\n logger.log('onReferences: no definition found at position', params.position);\n return [];\n }\n\n const results = getReferences(defSymbol.document, defSymbol.toPosition(), {\n reporter: progress,\n });\n\n logger.info({\n onReferences: 'found references',\n uri: defSymbol.uri,\n count: results.length,\n position: params.position,\n symbol: defSymbol.name,\n });\n\n if (results.length === 0) {\n logger.warning('onReferences: no references found', { uri: params.textDocument.uri, position: params.position });\n return [];\n }\n return results;\n }\n\n /**\n * bi-directional lookup of completion <-> definition under cursor location.\n */\n async onImplementation(params: ImplementationParams): Promise {\n this.logParams('onImplementation', params);\n const { doc } = this.getDefaults(params);\n if (!doc) return [];\n const symbols = analyzer.cache.getDocumentSymbols(doc.uri);\n const lastSymbols = filterLastPerScopeSymbol(symbols);\n logger.log('symbols', formatFishSymbolTree(lastSymbols));\n const result = analyzer.getImplementation(doc, params.position);\n logger.log('implementationResult', { result });\n return result;\n }\n\n // Probably should move away from `documentationCache`. It works but is too expensive memory wise.\n // REFACTOR into a procedure that conditionally determines output type needed.\n // Also plan to get rid of any other cache's, so that the garbage collector can do its job.\n async onHover(params: HoverParams): Promise {\n this.logParams('onHover', {\n params: {\n uri: params.textDocument.uri,\n position: params.position,\n },\n });\n const { doc, path, root, current } = this.getDefaults(params);\n if (!doc || !path || !root || !current) {\n return null;\n }\n\n let result: Hover | null = null;\n // case: `./dist/fish-lsp`\n if ((isCommand(current) || isCommandName(current)) && isPathNode(current)) {\n return {\n contents: enrichToMarkdown([\n `${md.bold('(command)')} - ${md.italic(current.text)}`,\n ].join('\\n')),\n };\n }\n\n if (isSourceCommandArgumentName(current)) {\n result = handleSourceArgumentHover(analyzer, current, doc);\n if (result) return result;\n }\n\n if (current.parent && isSourceCommandArgumentName(current.parent)) {\n result = handleSourceArgumentHover(analyzer, current.parent, doc);\n if (result) return result;\n }\n\n if (isAliasDefinitionName(current)) {\n result = analyzer.getDefinition(doc, params.position)?.toHover(doc.uri) || null;\n if (result) return result;\n }\n\n if (isArgparseVariableDefinitionName(current)) {\n logger.log('isArgparseDefinition');\n result = analyzer.getDefinition(doc, params.position)?.toHover(doc.uri) || null;\n return result;\n }\n\n if (isOption(current)) {\n // check that we aren't hovering a function option that is defined by\n // argparse inside the function, if we are then return it's hover value\n result = analyzer.getDefinition(doc, params.position)?.toHover(doc.uri) || null;\n if (result) return result;\n // otherwise we get the hover using inline documentation from `complete --do-complete {option}`\n result = await handleHover(\n analyzer,\n doc,\n params.position,\n current,\n this.documentationCache,\n );\n if (result) return result;\n }\n\n if (isConcatenatedValue(current)) {\n logger.log('isConcatenatedValue', { text: current.text, type: current.type });\n const parent = findParent(current, isConcatenation);\n const brace = findParent(current, isBraceExpansion);\n if (parent) {\n const res = await handleBraceExpansionHover(parent);\n if (res) return res;\n }\n if (brace) {\n const res = await handleBraceExpansionHover(brace);\n if (res) return res;\n }\n }\n // handle brace expansion hover\n if (isBraceExpansion(current)) {\n logger.log('isBraceExpansion', { text: current.text, type: current.type });\n const res = await handleBraceExpansionHover(current);\n if (res) return res;\n }\n if (current.parent && isBraceExpansion(current.parent)) {\n logger.log('isBraceExpansion: parent', { text: current.parent.text, type: current.parent.type });\n const res = await handleBraceExpansionHover(current.parent);\n if (res) return res;\n }\n\n if (isEndStdinCharacter(current)) {\n return handleEndStdinHover(current);\n }\n\n const { kindType, kindString } = symbolKindsFromNode(current);\n logger.log({ currentText: current.text, currentType: current.type, symbolKind: kindString });\n\n const prebuiltSkipType = [\n ...PrebuiltDocumentationMap.getByType('pipe'),\n ...isReturnStatusNumber(current) ? PrebuiltDocumentationMap.getByType('status') : [],\n ].find(obj => obj.name === current.text);\n\n // documentation for prebuilt variables without definition's\n // including $status, $pipestatus, $fish_pid, etc.\n // See: PrebuiltDocumentationMap.getByType('variable') for entire list\n // Also includes autoloaded variables: $fish_complete_path, $__fish_data_dir, etc...\n const isPrebuiltVariableWithoutDefinition = getVariableExpansionDocs(analyzer, doc, params.position);\n const prebuiltHover = isPrebuiltVariableWithoutDefinition(current);\n if (prebuiltHover) return prebuiltHover;\n\n const symbolItem = analyzer.getHover(doc, params.position);\n if (symbolItem) return symbolItem;\n if (prebuiltSkipType) {\n return {\n contents: enrichToMarkdown([\n `___${current.text}___ - _${getPrebuiltDocUrl(prebuiltSkipType)}_`,\n '___',\n `type - __(${prebuiltSkipType.type})__`,\n '___',\n `${prebuiltSkipType.description}`,\n ].join('\\n')),\n };\n }\n\n const definition = analyzer.getDefinition(doc, params.position);\n const allowsGlobalDocs = !definition || definition?.isGlobal();\n const symbolType = [\n 'function',\n 'class',\n 'variable',\n ].includes(kindString) ? kindType : undefined;\n\n const globalItem = await this.documentationCache.resolve(\n current.text.trim(),\n path,\n symbolType,\n );\n\n logger.log(`this.documentationCache.resolve() found ${!!globalItem}`, { docs: globalItem.docs });\n if (globalItem && globalItem.docs && allowsGlobalDocs) {\n logger.log({ ...globalItem });\n return {\n contents: {\n kind: MarkupKind.Markdown,\n value: globalItem.docs,\n },\n };\n }\n const fallbackHover = await handleHover(\n analyzer,\n doc,\n params.position,\n current,\n this.documentationCache,\n );\n logger.log({\n hover: { ...params },\n ...fallbackHover,\n });\n return fallbackHover;\n }\n\n async onRename(params: RenameParams): Promise {\n this.logParams('onRename', params);\n\n const { doc } = this.getDefaults(params);\n if (!doc) return null;\n\n const locations = getRenames(doc, params.position, params.newName);\n\n const changes: { [uri: string]: TextEdit[]; } = {};\n for (const location of locations) {\n const range = location.range;\n const uri = location.uri;\n const edits = changes[uri] || [];\n edits.push(TextEdit.replace(range, location.newText));\n changes[uri] = edits;\n }\n const workspaceEdit: WorkspaceEdit = {\n changes,\n };\n return workspaceEdit;\n }\n\n async onDocumentFormatting(params: DocumentFormattingParams): Promise {\n this.logParams('onDocumentFormatting', params);\n\n const { doc } = this.getDefaultsForPartialParams(params);\n if (!doc) return [];\n\n const formattedText = await formatDocumentWithIndentComments(doc).catch(error => {\n if (config.fish_lsp_show_client_popups) {\n connection.window.showErrorMessage(`Failed to format document: ${error}`);\n }\n return doc.getText(); // fallback to original text on error\n });\n\n return [{\n range: LSP.Range.create(\n LSP.Position.create(0, 0),\n LSP.Position.create(Number.MAX_VALUE, Number.MAX_VALUE),\n ),\n newText: formattedText,\n }];\n }\n\n async onDocumentTypeFormatting(params: DocumentFormattingParams): Promise {\n this.logParams('onDocumentTypeFormatting', params);\n const { doc } = this.getDefaultsForPartialParams(params);\n if (!doc) return [];\n\n const formattedText = await formatDocumentWithIndentComments(doc).catch(error => {\n connection.console.error(`Formatting error: ${error}`);\n if (config.fish_lsp_show_client_popups) {\n connection.window.showErrorMessage(`Failed to format document: ${error}`);\n }\n return doc.getText(); // fallback to original text on error\n });\n\n return [{\n range: LSP.Range.create(\n LSP.Position.create(0, 0),\n LSP.Position.create(Number.MAX_VALUE, Number.MAX_VALUE),\n ),\n newText: formattedText,\n }];\n }\n /**\n * Currently only works for whole line selections, in the future we should try to make every\n * selection a whole line selection.\n */\n async onDocumentRangeFormatting(params: DocumentRangeFormattingParams): Promise {\n this.logParams('onDocumentRangeFormatting', params);\n const { doc } = this.getDefaultsForPartialParams(params);\n if (!doc) return [];\n\n const range = params.range;\n const startOffset = doc.offsetAt(range.start);\n const endOffset = doc.offsetAt(range.end);\n\n // get the text\n const originalText = doc.getText();\n const selectedText = doc.getText().slice(startOffset, endOffset).trimStart();\n\n // Call the formatter 2 differently times, once for the whole document (to get the indentation level)\n // and a second time to get the specific range formatted\n const allText = await formatDocumentContent(originalText).catch((error) => {\n logger.error(`FormattingRange error: ${error}`);\n return selectedText; // fallback to original text on error\n });\n\n const formattedText = await formatDocumentContent(selectedText).catch(error => {\n logger.error(`FormattingRange error: ${error}`, {\n input: selectedText,\n range: range,\n });\n if (config.fish_lsp_show_client_popups) {\n connection.window.showErrorMessage(`Failed to format range: ${params.textDocument.uri}`);\n }\n return selectedText;\n });\n\n // Create a temporary TextDocumentItem with the formatted text, for passing to formatTextWithIndents()\n const newDoc = LspDocument.createTextDocumentItem(doc.uri, allText);\n\n // fixup formatting, so that we end with a single newline character (important for inserting `TextEdit`)\n const output = formatTextWithIndents(\n newDoc,\n range.start.line,\n formattedText.trim(),\n ) + '\\n';\n return [\n TextEdit.replace(\n params.range,\n output,\n ),\n ];\n }\n async onFoldingRanges(params: FoldingRangeParams): Promise {\n this.logParams('onFoldingRanges', params);\n\n const { path, doc } = this.getDefaultsForPartialParams(params);\n\n if (!doc) {\n throw new Error(`The document should not be opened in the folding range, file: ${path}`);\n }\n\n //this.analyzer.analyze(document)\n const symbols = analyzer.getDocumentSymbols(doc.uri);\n const flatSymbols = flattenNested(...symbols);\n logger.logPropertiesForEachObject(\n flatSymbols.filter((s) => s.kind === SymbolKind.Function),\n 'name',\n 'range',\n );\n\n const folds = flatSymbols\n .filter((symbol) => symbol.kind === SymbolKind.Function)\n .map((symbol) => symbol.toFoldingRange());\n\n folds.forEach((fold) => logger.log({ fold }));\n\n return folds;\n }\n\n async onSelectionRanges(params: SelectionRangeParams): Promise {\n this.logParams('onSelectionRanges', params);\n\n const { doc } = this.getDefaultsForPartialParams(params);\n if (!doc) {\n return null;\n }\n\n return getSelectionRanges(doc, params.positions);\n }\n\n async onInlayHints(params: InlayHintParams) {\n logger.log({ params });\n\n const { doc } = this.getDefaultsForPartialParams(params);\n if (!doc) return [];\n\n return getAllInlayHints(analyzer, doc);\n }\n\n // https://code.visualstudio.com/api/language-extensions/programmatic-language-features#codelens-show-actionable-context-information-within-source-code\n async onCodeLens(params: CodeLensParams): Promise {\n logger.log('onCodeLens', params);\n\n // const path = uriToPath(params.textDocument.uri);\n const doc = documents.get(params.textDocument.uri);\n\n if (!doc) return [];\n\n return getReferenceCountCodeLenses(analyzer, doc);\n }\n\n public onShowSignatureHelp(params: SignatureHelpParams): SignatureHelp | null {\n try {\n this.logParams('onShowSignatureHelp', params);\n const { doc, path } = this.getDefaults(params);\n if (!doc || !path) return null;\n\n const { line, lineRootNode, lineLastNode } = analyzer.parseCurrentLine(doc, params.position);\n if (line.trim() === '') return null;\n\n const currentCmd = findParentCommand(lineLastNode)!;\n const aliasSignature = this.completionMap.allOfKinds('alias').find(a => a.label === currentCmd.text);\n if (aliasSignature) return getAliasedCompletionItemSignature(aliasSignature);\n\n const varNode = getChildNodes(lineRootNode).find(c => isVariableDefinition(c));\n const lastCmd = getChildNodes(lineRootNode).filter(c => isCommand(c)).pop();\n logger.log({ line, lastCmds: lastCmd?.text });\n if (varNode && (line.startsWith('set') || line.startsWith('read')) && lastCmd?.text === lineRootNode.text.trim()) {\n const varName = varNode.text;\n const varDocs = PrebuiltDocumentationMap.getByName(varNode.text);\n if (!varDocs.length) return null;\n return {\n signatures: [\n {\n label: varName,\n documentation: {\n kind: 'markdown',\n value: varDocs.map(d => d.description).join('\\n'),\n },\n },\n ],\n activeSignature: 0,\n activeParameter: 0,\n };\n }\n if (isRegexStringSignature(line)) {\n const signature = getDefaultSignatures();\n logger.log('signature', signature);\n const cursorLineOffset = line.length - lineLastNode.endIndex;\n const { activeParameter } = findActiveParameterStringRegex(line, cursorLineOffset);\n signature.activeParameter = activeParameter;\n return signature;\n }\n const functionSignature = getFunctionSignatureHelp(\n analyzer,\n lineLastNode,\n line,\n params.position,\n );\n if (functionSignature) return functionSignature;\n } catch (err) {\n logger.error('onShowSignatureHelp', err);\n }\n return null;\n }\n\n /**\n * Parse and analyze a document. Adds diagnostics to the document, and finds `source` commands.\n * @param document - The document identifier to analyze\n */\n public analyzeDocument(document: LspDocument) {\n // remove existing symbols from analyzer.cache, as they will be re-collected\n analyzer.removeDocumentSymbols(document.uri);\n\n const { document: doc } = analyzer.analyze(document).ensureParsed();\n\n // re-indexes the workspace and changes the current workspace to the document (if needed)\n workspaceManager.handleOpenDocument(doc);\n workspaceManager.handleUpdateDocument(doc);\n\n currentDocument = doc;\n\n return {\n uri: doc.uri,\n path: doc.path,\n doc: doc,\n };\n }\n\n /**\n * Getter for information about the server.\n *\n * Mostly from the `../package.json` file of this module, but also includes\n * other useful entries about the server such as `out/build-time.json` object,\n * `manPath` and certain url entries that are slightly modified for easier\n * access to their links.\n */\n public get info() {\n return PkgJson;\n }\n\n /**\n * Getter for the completion item map (all commands available at startup)\n */\n public get completions(): CompletionItemMap {\n return this.completionMap;\n }\n\n public static get instance(): FishServer {\n if (!server) throw new Error('FishServer instance not initialized yet.');\n return server;\n }\n\n public static throwError(message: string) {\n throw new Error(message);\n }\n\n /////////////////////////////////////////////////////////////////////////////////////\n // HELPERS\n /////////////////////////////////////////////////////////////////////////////////////\n\n /**\n * Logs the params passed into a handler\n *\n * @param {string} methodName - the FishLsp method name that was called\n * @param {any[]} params - the params passed into the method\n */\n private logParams(methodName: string, ...params: any[]) {\n logger.log({ time: now(), handler: methodName, params });\n }\n\n // helper to get all the default objects needed when a TextDocumentPositionParam is passed\n // into a handler\n private getDefaults(params: TextDocumentPositionParams): {\n doc?: LspDocument;\n path?: string;\n root?: SyntaxNode | null;\n current?: SyntaxNode | null;\n } {\n const doc = documents.get(params.textDocument.uri);\n const path = doc?.path ?? uriToPath(params.textDocument.uri);\n\n if (!doc || !path) return { path };\n const root = analyzer.getRootNode(doc.uri);\n const current = analyzer.nodeAtPoint(\n doc.uri,\n params.position.line,\n params.position.character,\n );\n return { doc, path, root, current };\n }\n\n private getDefaultsForPartialParams(params: {\n textDocument: TextDocumentIdentifier;\n }): {\n doc?: LspDocument;\n path: string;\n root?: SyntaxNode | null;\n } {\n const doc = documents.get(params.textDocument.uri);\n const path = doc?.path ?? uriToPath(params.textDocument.uri);\n const root = doc ? analyzer.getRootNode(doc.uri) : undefined;\n return { doc, path, root };\n }\n\n private logDocument(request: string, document: LspDocument | undefined, options: {\n showDiagnostics?: boolean;\n showLastChangedSpan?: boolean;\n } = {\n showDiagnostics: false,\n showLastChangedSpan: false,\n }) {\n const extra: any = {};\n\n if (document) {\n const { uri, version, lineCount } = document;\n const content = document.getText();\n const truncated = content.length > 200 ? content.substring(0, 200) + '...' : content;\n if (options.showDiagnostics) {\n extra.diagnostics = { count: (analyzer.diagnostics.get(document.uri) || []).length };\n extra.diagnosticsInSpan = (analyzer.diagnostics.get(document.uri) || []).filter(d => {\n return document.lastChangedLineSpan\n ? rangeOverlapsLineSpan(d.range, document.lastChangedLineSpan)\n : false;\n }).map(d => ({\n text: d.code,\n line: d.range.start.line,\n span: document.lastChangedLineSpan,\n }));\n }\n if (options.showLastChangedSpan) {\n extra.lastChangedSpan = document.lastChangedLineSpan;\n }\n logger.log({\n time: now(),\n request,\n uri,\n version,\n content: truncated,\n lineCount,\n ...extra,\n });\n } else {\n logger.log({ time: now(), request, document: 'undefined', ...extra });\n }\n }\n\n static async setupForTestUtilities() {\n await setupProcessEnvExecFile();\n // const capabilities = params.capabilities;\n const initializeResult = Config.initialize({} as InitializeParams, connection);\n // set this only it it hasn't been set yet\n\n const initializeUris = getWorkspacePathsFromInitializationParams({} as InitializeParams);\n\n // Run these operations in parallel rather than sequentially\n const [\n cache,\n _workspaces,\n completionsMap,\n ] = await Promise.all([\n initializeDocumentationCache(),\n initializeDefaultFishWorkspaces(...initializeUris),\n CompletionItemMap.initialize(),\n ]);\n\n cachedDocumentation = cache;\n cachedCompletionMap = completionsMap;\n\n await Analyzer.initialize();\n\n const completions = await initializeCompletionPager(logger, completionsMap);\n\n server = new FishServer(\n completions,\n completionsMap,\n cache,\n {} as InitializeParams,\n );\n\n return { server, initializeResult };\n }\n}\n\n// Type export\nexport {\n FishServer,\n};\n"
},
{
"path": "src/signature.ts",
"content": "import {\n MarkupContent,\n MarkupKind,\n ParameterInformation,\n Position,\n SignatureHelp,\n SignatureInformation,\n SymbolKind,\n} from 'vscode-languageserver';\nimport { SyntaxNode } from 'web-tree-sitter';\nimport { ExtendedBaseJson, PrebuiltDocumentationMap } from './utils/snippets';\nimport { FishAliasCompletionItem } from './utils/completion/types';\nimport * as NodeTypes from './utils/node-types';\nimport * as TreeSitter from './utils/tree-sitter';\nimport { CompletionItemMap } from './utils/completion/startup-cache';\nimport { Option } from './parsing/options';\nimport { Analyzer } from './analyze';\nimport { md } from './utils/markdown-builder';\nimport { symbolKindToString } from './utils/translation';\n\nexport function buildSignature(label: string, value: string): SignatureInformation {\n return {\n label: label,\n documentation: {\n kind: 'markdown',\n value: value,\n },\n };\n}\n\nexport function getCurrentNodeType(input: string) {\n const prebuiltTypes = PrebuiltDocumentationMap.getByName(input);\n if (!prebuiltTypes || prebuiltTypes.length === 0) {\n return null;\n }\n let longestDocs = prebuiltTypes[0]!;\n for (const prebuilt of prebuiltTypes) {\n if (prebuilt.description.length > longestDocs.description.length) {\n longestDocs = prebuilt;\n }\n }\n return longestDocs;\n}\n\nexport function lineSignatureBuilder(lineRootNode: SyntaxNode, lineCurrentNode: SyntaxNode, _completeMmap: CompletionItemMap): SignatureHelp | null {\n const currentCmd = NodeTypes.findParentCommand(lineCurrentNode) || lineRootNode;\n const pipes = getPipes(lineRootNode);\n const varNode = getVariableNode(lineRootNode);\n const allCmds = getAllCommands(lineRootNode);\n const regexOption = getRegexOption(lineRootNode);\n\n if (pipes.length === 1) return getPipesSignature(pipes);\n\n switch (true) {\n case isStringWithRegex(currentCmd.text, regexOption):\n return getDefaultSignatures();\n\n case varNode && isSetOrReadWithVarNode(currentCmd?.text || lineRootNode.text, varNode, lineRootNode, allCmds):\n return getSignatureForVariable(varNode);\n\n case currentCmd?.text.startsWith('return') || lineRootNode.text.startsWith('return'):\n return getReturnStatusSignature();\n\n case allCmds.length === 1:\n return getCommandSignature(currentCmd);\n\n default:\n return null;\n }\n}\n\nexport function getPipes(rootNode: SyntaxNode): ExtendedBaseJson[] {\n const pipeNames = PrebuiltDocumentationMap.getByType('pipe');\n return TreeSitter.getChildNodes(rootNode).reduce((acc: ExtendedBaseJson[], node) => {\n const pipe = pipeNames.find(p => p.name === node.text);\n if (pipe) acc.push(pipe);\n return acc;\n }, []);\n}\n\nfunction getVariableNode(rootNode: SyntaxNode): SyntaxNode | undefined {\n return TreeSitter.getChildNodes(rootNode).find(c => NodeTypes.isVariableDefinition(c));\n}\n\nfunction getAllCommands(rootNode: SyntaxNode): SyntaxNode[] {\n return TreeSitter.getChildNodes(rootNode).filter(c => NodeTypes.isCommand(c));\n}\n\nfunction getRegexOption(rootNode: SyntaxNode): SyntaxNode | undefined {\n return TreeSitter.getChildNodes(rootNode).find(n => NodeTypes.isMatchingOption(n, Option.create('-r', '--regex')));\n}\n\nfunction isStringWithRegex(line: string, regexOption: SyntaxNode | undefined): boolean {\n return line.startsWith('string') && !!regexOption;\n}\n\nfunction isSetOrReadWithVarNode(line: string, varNode: SyntaxNode | undefined, rootNode: SyntaxNode, allCmds: SyntaxNode[]): boolean {\n return !!varNode && (line.startsWith('set') || line.startsWith('read')) && allCmds.pop()?.text === rootNode.text.trim();\n}\n\nfunction getSignatureForVariable(varNode: SyntaxNode): SignatureHelp | null {\n const output = getCurrentNodeType(varNode.text);\n if (!output) return null;\n return {\n signatures: [buildSignature(output.name, output.description)],\n activeSignature: 0,\n activeParameter: 0,\n };\n}\n\nfunction getReturnStatusSignature(): SignatureHelp {\n const output = PrebuiltDocumentationMap.getByType('status').map((o: ExtendedBaseJson) => `___${o.name}___ - _${o.description}_`).join('\\n');\n return {\n signatures: [buildSignature('$status', output)],\n activeSignature: 0,\n activeParameter: 0,\n };\n}\n\nfunction getPipesSignature(pipes: ExtendedBaseJson[]): SignatureHelp {\n return {\n signatures: pipes.map((o: ExtendedBaseJson) => buildSignature(o.name, `${o.name} - _${o.description}_`)),\n activeSignature: 0,\n activeParameter: 0,\n };\n}\n\nfunction getCommandSignature(firstCmd: SyntaxNode): SignatureHelp {\n const output = PrebuiltDocumentationMap.getByType('command').filter(n => n.name === firstCmd.text);\n return {\n signatures: [buildSignature(firstCmd.text, output.map((o: ExtendedBaseJson) => `${o.name} - _${o.description}_`).join('\\n'))],\n activeSignature: 0,\n activeParameter: 0,\n };\n}\n\nexport function getAliasedCompletionItemSignature(item: FishAliasCompletionItem): SignatureHelp {\n // const output = PrebuiltDocumentationMap.getByType('command').filter(n => n.name === firstCmd.text);\n return {\n signatures: [buildSignature(item.label, [\n '```fish',\n `${item.fishKind} ${item.label} ${item.detail}`,\n '```',\n ].join('\\n'))],\n activeSignature: 0,\n activeParameter: 0,\n };\n}\n\nexport function regexStringSignature(): SignatureInformation {\n const signatureDoc: MarkupContent = {\n kind: 'markdown',\n value: [\n markdownStringRepetitions,\n markdownStringCharClasses,\n markdownStringGroups,\n ].join('\\n---\\n'),\n };\n return {\n label: 'Regex Patterns',\n documentation: signatureDoc,\n };\n}\n\nfunction regexStringCharacterSets(): SignatureInformation {\n const inputText: string = [\n markdownStringRepetitions,\n markdownStringCharClasses,\n markdownStringGroups,\n ].join('\\n---\\n');\n const parameters: ParameterInformation[] = [\n ParameterInformation.create('argv[1]', inputText),\n ParameterInformation.create('argv[2]', inputText),\n ];\n return {\n label: 'Regex Groups',\n documentation: {\n kind: 'markdown',\n value: markdownStringCharacterSets,\n } as MarkupContent,\n parameters: parameters,\n activeParameter: 0,\n };\n}\n/**\n * Checks if a flag matches either a short flag (-r) or a long flag (--regex)\n * For short flags, it will check if the flag is part of a combined flag string (-re)\n *\n * @param text The text to check\n * @param shortFlag The short flag to check for (e.g. 'r')\n * @param longFlag The long flag to check for (e.g. 'regex')\n * @returns true if the text matches either the short or long flag\n */\nexport function isMatchingOption(\n text: string,\n options: { shortOption?: string; longOption?: string; },\n): boolean {\n // Early return if text doesn't start with a dash\n if (!text.startsWith('-')) return false;\n\n // Handle long options (--option)\n if (text.startsWith('--') && options.longOption) {\n // Remove any equals sign and following text (--option=value)\n const cleanText = text.includes('=') ? text.slice(0, text.indexOf('=')) : text;\n return cleanText === `--${options.longOption}`;\n }\n\n // Handle short options (-o)\n if (text.startsWith('-') && options.shortOption) {\n // Check if the short option is included in the characters after the dash\n // This handles combined flags like -abc where we want to check for 'a'\n return text.slice(1).includes(options.shortOption);\n }\n\n return false;\n}\n\n/**\n * Determines the active parameter index based on cursor position\n *\n * @param line The complete command line\n * @param commandName The name of the command\n * @param cursorPosition The position of the cursor in the line\n * @returns The index of the active parameter\n */\nexport function getActiveParameterIndex(line: string, commandName: string, needsSubcommand: boolean, cursorPosition: number): number {\n // Split the line into tokens\n const tokens = line.trim().split(/\\s+/);\n let currentPosition = 0;\n let paramIndex = 0;\n const commands = commandName.split(' ');\n let previousWasCommand = false;\n for (const token of tokens) {\n if (commands.includes(token) || ['if', 'else if', 'switch', 'case'].includes(token)) {\n // Skip the command name\n cursorPosition += token.length + 1; // +1 for the space\n previousWasCommand = true;\n continue;\n }\n // Skip the subcommand\n if (needsSubcommand && previousWasCommand) {\n cursorPosition += token.length + 1; // +1 for the space\n previousWasCommand = false;\n continue;\n }\n break;\n }\n\n // Find which parameter the cursor is in\n for (let i = 1; i < tokens.length; i++) {\n const token = tokens[i];\n\n // Check if cursor is before this token\n if (currentPosition + token!.length >= cursorPosition) {\n break;\n }\n\n // If token is a flag, it's not a parameter\n if (token!.startsWith('-')) {\n // Skip flag parameter if it's a value flag\n if (i + 1 < tokens.length && !tokens[i + 1]!.startsWith('-')) {\n i++; // Skip the value\n currentPosition += tokens[i]!.length + 1;\n }\n } else {\n // This is a parameter\n paramIndex++;\n }\n\n currentPosition += token!.length + 1; // +1 for the space\n }\n\n return paramIndex;\n}\n\n/**\n * Check if the input line is a string command with regex option\n */\nexport function isRegexStringSignature(line: string): boolean {\n const tokens = line.split(' ');\n const hasStringCommand = tokens.some(token => token === 'string') && !tokens.some(token => token === '--');\n\n if (hasStringCommand) {\n return tokens.some(token =>\n isMatchingOption(token, {\n shortOption: 'r',\n longOption: 'regex',\n }),\n );\n }\n\n return false;\n}\n\nexport function findActiveParameterStringRegex(\n line: string,\n cursorPosition: number,\n): {\n isRegex: boolean;\n activeParameter: number;\n } {\n const tokens = line.split(' ');\n const hasStringCommand = tokens.some(token => token === 'string');\n\n const isRegex = hasStringCommand && tokens.some(token =>\n isMatchingOption(token, {\n shortOption: 'r',\n longOption: 'regex',\n }),\n );\n\n const activeParameter = isRegex ? getActiveParameterIndex(line, 'string ', true, cursorPosition) : 0;\n return { isRegex, activeParameter };\n}\ntype signatureType = 'stringRegexPatterns' | 'stringRegexCharacterSets';\n\nexport const signatureIndex: { [str in signatureType]: number } = {\n stringRegexPatterns: 0,\n stringRegexCharacterSets: 1,\n};\n\nexport function getDefaultSignatures(): SignatureHelp {\n return {\n activeParameter: 0,\n activeSignature: 0,\n signatures: [\n regexStringSignature(),\n regexStringCharacterSets(),\n ],\n };\n}\n\n/**\n * Creates a signature help for a function\n *\n * @param analyzer The analyzer instance\n * @param lineLastNode The last node in the current line\n * @param line The current line text\n * @param position The cursor position\n * @returns A SignatureHelp object or null\n */\nexport function getFunctionSignatureHelp(\n analyzer: Analyzer,\n lineLastNode: SyntaxNode,\n line: string,\n position: Position,\n): SignatureHelp | null {\n // Find the function symbol based on the node's parent's first named child\n const functionName = lineLastNode.parent?.firstNamedChild?.text.trim();\n if (!functionName) return null;\n\n const funcSymbol = analyzer.findSymbol((symbol, _) => symbol.name === functionName);\n if (!funcSymbol || funcSymbol.kind !== SymbolKind.Function) return null;\n\n // Get all parameter names, filtering out non-function variables\n const paramNames = funcSymbol.children\n .filter(s => s.fishKind === 'FUNCTION_VARIABLE' && s.name !== 'argv');\n\n // Add argv as the last parameter if it exists\n const argvParam = funcSymbol.children\n .find(s => s.fishKind === 'FUNCTION_VARIABLE' && s.name === 'argv');\n if (argvParam) {\n paramNames.push(argvParam);\n }\n\n // Create parameter information for each parameter\n const paramDocs: ParameterInformation[] = paramNames.map((p, idx) => {\n const markdownString = p.toMarkupContent().value.split(md.separator());\n // set the labels for `argv` to be `$argv[1..-1]` and the rest to be `$argv[1]`\n const label = p.name === 'argv'\n ? `$${p.name}[${idx + 1}..-1]`\n : p.name;\n // set the documentation to be the first line of the markdown string\n const newContentString = p.name === 'argv'\n ? [\n '',\n `${md.bold(`(${symbolKindToString(p.kind)})`)} ${label}`,\n md.separator(),\n `This parameter corresponds to ${md.inlineCode(`$argv[${idx + 1}..-1]`)} in the function.`,\n '',\n ].join(md.newline())\n : [\n '',\n `${md.bold(`(${symbolKindToString(p.kind)})`)} ${md.inlineCode(p.name)}`,\n md.separator(),\n `This parameter corresponds to ${md.inlineCode(`$argv[${idx + 1}]`)} in the function.`,\n '',\n ].join(md.newline());\n // set the documentation\n const newValue = p.name === 'argv'\n ? [\n newContentString,\n ].join(md.separator())\n : [\n newContentString,\n markdownString.slice(3, 4),\n ].join(md.separator());\n // set content\n const newContent = {\n kind: MarkupKind.Markdown,\n value: newValue,\n };\n return {\n label: label,\n documentation: newContent,\n };\n });\n\n // Create the signature label with the function name and parameter names\n const label = `${funcSymbol.name} ${paramDocs.map(p => p.label).join(' ')}`.trim();\n\n // Create the signature information\n const signature = SignatureInformation.create(\n label,\n funcSymbol.detail,\n ...paramDocs,\n );\n signature.documentation = {\n kind: MarkupKind.Markdown,\n value: funcSymbol.detail || 'No documentation available',\n };\n\n // Calculate the active parameter based on cursor position\n const activeParameter = calculateActiveParameter(line, position) - 1;\n\n return {\n signatures: [signature],\n activeSignature: 0,\n activeParameter: Math.min(activeParameter, paramNames.length - 1),\n };\n}\n\n/**\n * Calculates which parameter the cursor is currently on\n *\n * @param line The current line text\n * @param position The cursor position\n * @returns The index of the active parameter\n */\nfunction calculateActiveParameter(line: string, position: Position): number {\n const textBeforeCursor = line.substring(0, position.character);\n const tokens = textBeforeCursor.trim().split(/\\s+/);\n\n // First token is the function name, so we start at 0 (first parameter)\n // and count parameters (non-flag arguments)\n let paramCount = 0;\n\n // Skip the first token (function name)\n for (let i = 1; i < tokens.length; i++) {\n const token = tokens[i];\n // Skip flags and their values\n if (token?.startsWith('-')) {\n // If this is a flag that takes a value and the next token exists\n // and isn't a flag, skip that too\n if (i + 1 < tokens.length && !tokens[i + 1]?.startsWith('-')) {\n i++;\n }\n continue;\n }\n\n // Count this as a parameter\n paramCount++;\n }\n\n return paramCount;\n}\n// REGEX STRING LINES\nconst markdownStringRepetitions = [\n 'Repetitions',\n '-----------',\n '- __*__ refers to 0 or more repetitions of the previous expression',\n '- __+__ 1 or more',\n '- __?__ 0 or 1.',\n '- __{n}__ to exactly n (where n is a number)',\n '- __{n,m}__ at least n, no more than m.',\n '- __{n,}__ n or more',\n].join('\\n');\n\nconst markdownStringCharClasses = [\n 'Character Classes',\n '-----------------',\n '- __.__ any character except newline',\n '- __\\\\d__ a decimal digit and __\\\\D__, not a decimal digit',\n '- __\\\\s__ whitespace and __\\\\S__, not whitespace',\n '- __\\\\w__ a “word” character and __\\\\W__, a “non-word” character',\n '- __\\\\b__ a “word” boundary, and __\\\\B__, not a word boundary',\n '- __[...]__ (where “…” is some characters) is a character set',\n '- __[^...]__ is the inverse of the given character set',\n '- __[x-y]__ is the range of characters from x-y',\n '- __[[:xxx:]]__ is a named character set',\n '- __[[:^xxx:]]__ is the inverse of a named character set',\n].join('\\n');\n\nconst markdownStringCharacterSets = [\n '__[[:alnum:]]__ : “alphanumeric”',\n '__[[:alpha:]]__ : “alphabetic”',\n '__[[:ascii:]]__ : “0-127”',\n '__[[:blank:]]__ : “space or tab”',\n '__[[:cntrl:]]__ : “control character”',\n '__[[:digit:]]__ : “decimal digit”',\n '__[[:graph:]]__ : “printing, excluding space”',\n '__[[:lower:]]__ : “lower case letter”',\n '__[[:print:]]__ : “printing, including space”',\n '__[[:punct:]]__ : “printing, excluding alphanumeric”',\n '__[[:space:]]__ : “white space”',\n '__[[:upper:]]__ : “upper case letter”',\n '__[[:word:]]__ : “same as w”',\n '__[[:xdigit:]]__ : “hexadecimal digit”',\n].join('\\n');\n\nconst markdownStringGroups = [\n 'Groups',\n '------',\n '- __(...)__ is a capturing group',\n '- __(?:...)__ is a non-capturing group',\n '- __\\\\n__ is a backreference (where n is the number of the group, starting with 1)',\n '- __$n__ is a reference from the replacement expression to a group in the match expression.',\n].join('\\n');\n"
},
{
"path": "src/snippets/envVariables.json",
"content": "[\n {\n \"name\": \"_\",\n \"description\": \"the name of the currently running command (though this is deprecated, and the use of status current-command is preferred).\"\n },\n {\n \"name\": \"argv\",\n \"description\": \"a list of arguments to the shell or function. argv is only defined when inside a function call, or if fish was invoked with a list of arguments, like fish myscript.fish foo bar. This variable can be changed.\"\n },\n {\n \"name\": \"argv_opts\",\n \"description\": \"argparse sets this to the list of successfully parsed options, including option-arguments. This variable can be changed.\"\n },\n {\n \"name\": \"CMD_DURATION\",\n \"description\": \"the runtime of the last command in milliseconds.\"\n },\n {\n \"name\": \"COLUMNS\",\n \"description\": \"the current size of the terminal in width. These values are only used by fish if the operating system does not report the size of the terminal. Both variables must be set in that case otherwise a default of 80x24 will be used. They are updated when the window size changes.\"\n },\n {\n \"name\": \"LINES\",\n \"description\": \"the current size of the terminal in height. These values are only used by fish if the operating system does not report the size of the terminal. Both variables must be set in that case otherwise a default of 80x24 will be used. They are updated when the window size changes.\"\n },\n {\n \"name\": \"fish_kill_signal\",\n \"description\": \"the signal that terminated the last foreground job, or 0 if the job exited normally.\"\n },\n {\n \"name\": \"fish_killring\",\n \"description\": \"a list of entries in fish’s kill ring of cut text.\"\n },\n {\n \"name\": \"fish_read_limit\",\n \"description\": \"how many bytes fish will process with read or in a command substitution.\"\n },\n {\n \"name\": \"fish_pid\",\n \"description\": \"the process ID (PID) of the shell.\"\n },\n {\n \"name\": \"history\",\n \"description\": \"a list containing the last commands that were entered.\"\n },\n {\n \"name\": \"HOME\",\n \"description\": \"the user’s home directory. This variable can be changed.\"\n },\n {\n \"name\": \"hostname\",\n \"description\": \"the machine’s hostname.\"\n },\n {\n \"name\": \"IFS\",\n \"description\": \"the internal field separator that is used for word splitting with the read builtin. Setting this to the empty string will also disable line splitting in command substitution. This variable can be changed.\"\n },\n {\n \"name\": \"last_pid\",\n \"description\": \"the process ID (PID) of the last background process.\"\n },\n {\n \"name\": \"PWD\",\n \"description\": \"the current working directory.\"\n },\n {\n \"name\": \"pipestatus\",\n \"description\": \"a list of exit statuses of all processes that made up the last executed pipe. See exit status.\"\n },\n {\n \"name\": \"SHLVL\",\n \"description\": \"the level of nesting of shells. Fish increments this in interactive shells, otherwise it only passes it along.\"\n },\n {\n \"name\": \"status\",\n \"description\": \"the exit status of the last foreground job to exit. If the job was terminated through a signal, the exit status will be 128 plus the signal number.\"\n },\n {\n \"name\": \"status_generation\",\n \"description\": \"the “generation” count of $status. This will be incremented only when the previous command produced an explicit status. (For example, background jobs will not increment this).\"\n },\n {\n \"name\": \"TERM\",\n \"description\": \"the type of the current terminal. When fish tries to determine how the terminal works - how many colors it supports, what sequences it sends for keys and other things - it looks at this variable and the corresponding information in the terminfo database (see man terminfo). Note: Typically this should not be changed as the terminal sets it to the correct value.\"\n },\n {\n \"name\": \"USER\",\n \"description\": \"the current username. This variable can be changed.\"\n },\n {\n \"name\": \"EUID\",\n \"description\": \"the current effective user id, set by fish at startup. This variable can be changed.\"\n },\n {\n \"name\": \"version\",\n \"description\": \"the version of the currently running fish (also available as FISH_VERSION for backward compatibility).\"\n }\n]\n"
},
{
"path": "src/snippets/fishlspEnvVariables.json",
"content": "[\n {\n \"name\": \"fish_lsp_enabled_handlers\",\n \"description\": \"Enables the fish-lsp handlers. By default, all stable handlers are enabled.\",\n \"shortDescription\": \"server handlers to enable\",\n \"exactMatchOptions\": true,\n \"options\": [\n \"complete\",\n \"hover\",\n \"rename\",\n \"definition\",\n \"implementation\",\n \"reference\",\n \"logger\",\n \"formatting\",\n \"formatRange\",\n \"typeFormatting\",\n \"codeAction\",\n \"codeLens\",\n \"folding\",\n \"selectionRange\",\n \"signature\",\n \"executeCommand\",\n \"inlayHint\",\n \"highlight\",\n \"diagnostic\",\n \"popups\",\n \"semanticTokens\"\n ],\n \"defaultValue\": [],\n \"valueType\": \"array\"\n },\n {\n \"name\": \"fish_lsp_disabled_handlers\",\n \"description\": \"Disables the fish-lsp handlers. By default, non-stable handlers are disabled.\",\n \"shortDescription\": \"server handlers to disable\",\n \"exactMatchOptions\": true,\n \"options\": [\n \"complete\",\n \"hover\",\n \"rename\",\n \"definition\",\n \"implementation\",\n \"reference\",\n \"logger\",\n \"formatting\",\n \"formatRange\",\n \"typeFormatting\",\n \"codeAction\",\n \"codeLens\",\n \"folding\",\n \"selectionRange\",\n \"signature\",\n \"executeCommand\",\n \"inlayHint\",\n \"highlight\",\n \"diagnostic\",\n \"popups\",\n \"semanticTokens\"\n ],\n \"defaultValue\": [],\n \"valueType\": \"array\"\n },\n {\n \"name\": \"fish_lsp_commit_characters\",\n \"description\": \"Array of the completion expansion characters.\\n\\nSingle letter values only.\\n\\nCommit characters are used to select completion items, as shortcuts.\",\n \"shortDescription\": \"commit characters that select completion items\",\n \"exactMatchOptions\": false,\n \"options\": [\n \".\",\n \",\",\n \";\",\n \":\",\n \"(\",\n \")\",\n \"[\",\n \"]\",\n \"{\",\n \"}\",\n \"<\",\n \">\",\n \"'\",\n \"\\\"\",\n \"=\",\n \"+\",\n \"-\",\n \"/\",\n \"\\\\\",\n \"|\",\n \"&\",\n \"%\",\n \"$\",\n \"#\",\n \"@\",\n \"!\",\n \"?\",\n \"*\",\n \"^\",\n \"`\",\n \"~\",\n \"\\\\t\",\n \" \"\n ],\n \"defaultValue\": [\n \"\\\\t\",\n \";\",\n \" \"\n ],\n \"valueType\": \"array\"\n },\n {\n \"name\": \"fish_lsp_log_file\",\n \"description\": \"A path to the fish-lsp's logging file. Empty string disables logging.\",\n \"shortDescription\": \"path to the fish-lsp's log file\",\n \"exactMatchOptions\": false,\n \"options\": [\n \"/tmp/fish_lsp.log\",\n \"~/path/to/fish_lsp/logs.txt\"\n ],\n \"defaultValue\": \"\",\n \"valueType\": \"string\"\n },\n {\n \"name\": \"fish_lsp_logfile\",\n \"description\": \"DEPRECATED. USE `fish_lsp_log_file` instead.\\n\\nPath to the logging file.\",\n \"shortDescription\": \"path to the fish-lsp's log file\",\n \"isDeprecated\": true,\n \"exactMatchOptions\": false,\n \"options\": [\n \"/tmp/fish_lsp.logs\",\n \"~/path/to/fish_lsp/logs.txt\"\n ],\n \"defaultValue\": \"\",\n \"valueType\": \"string\"\n },\n {\n \"name\": \"fish_lsp_log_level\",\n \"description\": \"The logging severity level for displaying messages in the log file.\",\n \"shortDescription\": \"minimum log level to include in the log file\",\n \"exactMatchOptions\": true,\n \"options\": [\n \"debug\",\n \"info\",\n \"warning\",\n \"error\",\n \"log\"\n ],\n \"defaultValue\": \"\",\n \"valueType\": \"string\"\n },\n {\n \"name\": \"fish_lsp_all_indexed_paths\",\n \"description\": \"The fish file paths to include in the fish-lsp's startup indexing, as workspaces.\\n\\nOrder matters (usually place `$__fish_config_dir` before `$__fish_data_dir`).\",\n \"shortDescription\": \"directories that the server should always index on startup\",\n \"exactMatchOptions\": false,\n \"options\": [\n \"$HOME/.config/fish\",\n \"/usr/share/fish\",\n \"$__fish_config_dir\",\n \"$__fish_data_dir\"\n ],\n \"defaultValue\": [\n \"$__fish_config_dir\",\n \"$__fish_data_dir\"\n ],\n \"valueType\": \"array\"\n },\n {\n \"name\": \"fish_lsp_modifiable_paths\",\n \"description\": \"The fish file paths, for workspaces where global symbols can be renamed by the user.\",\n \"shortDescription\": \"indexed paths that can be modified\",\n \"exactMatchOptions\": false,\n \"options\": [\n \"/usr/share/fish\",\n \"$HOME/.config/fish\",\n \"$__fish_data_dir\",\n \"$__fish_config_dir\"\n ],\n \"defaultValue\": [\n \"$__fish_config_dir\"\n ],\n \"valueType\": \"array\"\n },\n {\n \"name\": \"fish_lsp_diagnostic_disable_error_codes\",\n \"description\": \"The diagnostics error codes to disable from the fish-lsp's diagnostics.\",\n \"shortDescription\": \"diagnostic codes to disable\",\n \"exactMatchOptions\": true,\n \"options\": [\n 1001,\n 1002,\n 1003,\n 1004,\n 1005,\n 2001,\n 2002,\n 2003,\n 2004,\n 3001,\n 3002,\n 3003,\n 4001,\n 4002,\n 4003,\n 4004,\n 4005,\n 4006,\n 4007,\n 4008,\n 5001,\n 5555,\n 6001,\n 7001,\n 8001,\n 9999\n ],\n \"defaultValue\": [],\n \"valueType\": \"array\"\n },\n {\n \"name\": \"fish_lsp_max_diagnostics\",\n \"description\": \"The maximum number of diagnostics to return per file.\\n\\nUsing value `0` means unlimited diagnostics.\\n\\nTo entirely disable diagnostics use `fish_lsp_disabled_handlers`\",\n \"shortDescription\": \"maximum number of diagnostics to return per file\",\n \"exactMatchOptions\": false,\n \"options\": [\n 0,\n 10,\n 25,\n 50,\n 100,\n 250\n ],\n \"defaultValue\": 0,\n \"valueType\": \"number\"\n },\n\n {\n \"name\": \"fish_lsp_enable_experimental_diagnostics\",\n \"description\": \"Enables the experimental diagnostics feature, using `fish --no-execute`.\\n\\nThis feature will enable the diagnostic error code 9999 (disabled by default).\",\n \"shortDescription\": \"enable fish-lsp's experimental diagnostics\",\n \"exactMatchOptions\": true,\n \"options\": [\n true,\n false\n ],\n \"defaultValue\": false,\n \"valueType\": \"boolean\"\n },\n {\n \"name\": \"fish_lsp_strict_conditional_command_warnings\",\n \"description\": \"Diagnostic `3002` includes/excludes conditionally chained commands to explicitly check existence.\\n\\nENABLED EXAMPLE: `command -q ls && command ls || echo 'no ls'`\\n\\nDISABLED EXAMPLE: `command ls || echo 'no ls'`\",\n \"shortDescription\": \"diagnostic `3002` show warnings for syntax like `command ls || echo 'no ls'`\",\n \"exactMatchOptions\": true,\n \"options\": [\n true,\n false\n ],\n \"defaultValue\": false,\n \"valueType\": \"boolean\"\n },\n {\n \"name\": \"fish_lsp_prefer_builtin_fish_commands\",\n \"description\": \"Show diagnostic `2004` which warns the user when they are using a recognized external command that can be replaced by an equivalent fish builtin command.\",\n \"shortDescription\": \"prefer built-in fish commands over external shell commands\",\n \"exactMatchOptions\": true,\n \"options\": [\n true,\n false\n ],\n \"defaultValue\": false,\n \"valueType\": \"boolean\"\n },\n {\n \"name\": \"fish_lsp_allow_fish_wrapper_functions\",\n \"description\": \"Show warnings when `alias`, `export`, etc... are used instead of their equivalent fish builtin commands.\\n\\nSome commands will provide quick-fixes to convert this diagnostic to its equivalent fish command.\\n\\nDiagnostic `2002` is shown when this setting is false, and hidden when true.\",\n \"shortDescription\": \"prefer the user to use primitive fish commands instead of wrapper utilities common in other shells\",\n \"exactMatchOptions\": true,\n \"options\": [\n true,\n false\n ],\n \"defaultValue\": true,\n \"valueType\": \"boolean\"\n },\n {\n \"name\": \"fish_lsp_require_autoloaded_functions_to_have_description\",\n \"description\": \"Show warning diagnostic `4008` when an autoloaded function definition does not have a description `function -d/--description '...'; end;`\",\n \"shortDescription\": \"enable showing diagnostic `4008`\",\n \"exactMatchOptions\": true,\n \"options\": [\n true,\n false\n ],\n \"defaultValue\": true,\n \"valueType\": \"boolean\"\n },\n {\n \"name\": \"fish_lsp_max_background_files\",\n \"description\": \"The maximum number of background files to read into buffer on startup.\",\n \"shortDescription\": \"maximum number of files to analyze in the background on startup\",\n \"exactMatchOptions\": false,\n \"options\": [\n 100,\n 250,\n 500,\n 1000,\n 5000,\n 10000\n ],\n \"defaultValue\": 10000,\n \"valueType\": \"number\"\n },\n {\n \"name\": \"fish_lsp_show_client_popups\",\n \"description\": \"Should the client receive pop-up window notification requests from the fish-lsp server?\",\n \"shortDescription\": \"send `connection/window/*` requests in the server\",\n \"exactMatchOptions\": true,\n \"options\": [\n true,\n false\n ],\n \"defaultValue\": false,\n \"valueType\": \"boolean\"\n },\n {\n \"name\": \"fish_lsp_single_workspace_support\",\n \"description\": \"Try to limit the fish-lsp's workspace searching to only the current workspace open.\",\n \"shortDescription\": \"limit workspace searching to only the current workspace\",\n \"exactMatchOptions\": true,\n \"options\": [\n true,\n false\n ],\n \"defaultValue\": false,\n \"valueType\": \"boolean\"\n },\n {\n \"name\": \"fish_lsp_ignore_paths\",\n \"description\": \"Glob paths to never search when indexing their parent folder\",\n \"shortDescription\": \"paths to ignore when indexing\",\n \"exactMatchOptions\": false,\n \"options\": [\n \"**/.git/**\",\n \"**/node_modules/**\",\n \"**/vendor/**\",\n \"**/__pycache__/**\",\n \"**/docker/**\",\n \"**/containerized/**\",\n \"**/*.log\",\n \"**/tmp/**\"\n ],\n \"defaultValue\": [\n \"**/.git/**\",\n \"**/node_modules/**\",\n \"**/containerized/**\",\n \"**/docker/**\"\n ],\n \"valueType\": \"array\"\n },\n {\n \"name\": \"fish_lsp_max_workspace_depth\",\n \"description\": \"The maximum depth for the lsp to search when starting up.\",\n \"shortDescription\": \"maximum directory depth to search for fish files on startup\",\n \"exactMatchOptions\": false,\n \"options\": [\n 1,\n 2,\n 3,\n 4,\n 5,\n 6,\n 7,\n 8,\n 9,\n 10,\n 15,\n 20\n ],\n \"defaultValue\": 5,\n \"valueType\": \"number\"\n },\n {\n \"name\": \"fish_lsp_fish_path\",\n \"description\": \"A path to the fish executable to use exposing fish binary to use in server's spawned child_processes.\\n\\nTypically, this is used in the language-client's `FishServer.initialize(connection, InitializeParams.initializationOptions)`, NOT as an environment variable\",\n \"shortDescription\": \"specific binary to use for executing 'fish' commands inside server\",\n \"exactMatchOptions\": false,\n \"options\": [\n \"fish\",\n \"/usr/bin/fish\",\n \"/usr/.local/bin/fish\",\n \"~/.local/bin/fish\"\n ],\n \"defaultValue\": \"fish\",\n \"valueType\": \"string\"\n }\n]\n"
},
{
"path": "src/snippets/functions.json",
"content": "[\n {\n \"name\": \"__fish_any_arg_in\",\n \"file\": \"$__fish_data_dir/functions/__fish_any_arg_in.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_anyeditor\",\n \"file\": \"$__fish_data_dir/functions/__fish_anyeditor.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_anypager\",\n \"file\": \"$__fish_data_dir/functions/__fish_anypager.fish\",\n \"flags\": [\n \"--description Print a pager to use\"\n ],\n \"description\": \"Print a pager to use\"\n },\n {\n \"name\": \"__fish_anypython\",\n \"file\": \"$__fish_data_dir/functions/__fish_anypython.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_append\",\n \"file\": \"$__fish_data_dir/functions/__fish_append.fish\",\n \"flags\": [\n \"-d Internal completion function for appending string to the commandline\",\n \"--argument-names sep\"\n ],\n \"description\": \"Internal completion function for appending string to the commandline\"\n },\n {\n \"name\": \"__fish_apropos\",\n \"file\": \"$__fish_data_dir/functions/__fish_apropos.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_argcomplete_complete\",\n \"file\": \"$__fish_data_dir/functions/__fish_argcomplete_complete.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_cache_put\",\n \"file\": \"$__fish_data_dir/functions/__fish_cache_put.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_cache_sourced_completions\",\n \"file\": \"$__fish_data_dir/functions/__fish_cache_sourced_completions.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_cached\",\n \"file\": \"$__fish_data_dir/functions/__fish_cached.fish\",\n \"flags\": [\n \"--description Cache the command output for a given amount of time\"\n ],\n \"description\": \"Cache the command output for a given amount of time\"\n },\n {\n \"name\": \"__fish_cancel_commandline\",\n \"file\": \"$__fish_data_dir/functions/__fish_cancel_commandline.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_change_key_bindings\",\n \"file\": \"$__fish_data_dir/functions/__fish_change_key_bindings.fish\",\n \"flags\": [\n \"--argument-names bindings\"\n ]\n },\n {\n \"name\": \"__fish_cmd__complete_args\",\n \"file\": \"$__fish_data_dir/functions/__fish_cmd__complete_args.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_commandline_is_singlequoted\",\n \"file\": \"$__fish_data_dir/functions/__fish_commandline_is_singlequoted.fish\",\n \"flags\": [\n \"--description Return 0 if the current token has an open single-quote\"\n ],\n \"description\": \"Return 0 if the current token has an open single-quote\"\n },\n {\n \"name\": \"__fish_complete_atool_archive_contents\",\n \"file\": \"$__fish_data_dir/functions/__fish_complete_atool_archive_contents.fish\",\n \"flags\": [\n \"--description List archive contents\"\n ],\n \"description\": \"List archive contents\"\n },\n {\n \"name\": \"__fish_complete_bittorrent\",\n \"file\": \"$__fish_data_dir/functions/__fish_complete_bittorrent.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_complete_blockdevice\",\n \"file\": \"$__fish_data_dir/functions/__fish_complete_blockdevice.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_complete_cd\",\n \"file\": \"$__fish_data_dir/functions/__fish_complete_cd.fish\",\n \"flags\": [\n \"-d Completions for the cd command\"\n ],\n \"description\": \"Completions for the cd command\"\n },\n {\n \"name\": \"__fish_complete_clang\",\n \"file\": \"$__fish_data_dir/functions/__fish_complete_clang.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_complete_command\",\n \"file\": \"$__fish_data_dir/functions/__fish_complete_command.fish\",\n \"flags\": [\n \"--description Complete using all available commands\"\n ],\n \"description\": \"Complete using all available commands\"\n },\n {\n \"name\": \"__fish_complete_convert_options\",\n \"file\": \"$__fish_data_dir/functions/__fish_complete_convert_options.fish\",\n \"flags\": [\n \"--description Complete Convert options\",\n \"--argument-names what\"\n ],\n \"description\": \"Complete Convert options\"\n },\n {\n \"name\": \"__fish_complete_directories\",\n \"file\": \"$__fish_data_dir/functions/__fish_complete_directories.fish\",\n \"flags\": [\n \"-d Complete directory prefixes\",\n \"--argument-names comp\"\n ],\n \"description\": \"Complete directory prefixes\"\n },\n {\n \"name\": \"__fish_complete_docutils\",\n \"file\": \"$__fish_data_dir/functions/__fish_complete_docutils.fish\",\n \"flags\": [\n \"-a cmd\"\n ]\n },\n {\n \"name\": \"__fish_complete_freedesktop_icons\",\n \"file\": \"$__fish_data_dir/functions/__fish_complete_freedesktop_icons.fish\",\n \"flags\": [\n \"-d List installed icon names according to `https://specifications.freedesktop.org/icon-theme-spec/0.13/`\"\n ],\n \"description\": \"List installed icon names according to `https://specifications.freedesktop.org/icon-theme-spec/0.13/`\"\n },\n {\n \"name\": \"__fish_complete_ftp\",\n \"file\": \"$__fish_data_dir/functions/__fish_complete_ftp.fish\",\n \"flags\": [\n \"--argument-names ftp\"\n ]\n },\n {\n \"name\": \"__fish_complete_gpg\",\n \"file\": \"$__fish_data_dir/functions/__fish_complete_gpg.fish\",\n \"flags\": [\n \"-a __fish_complete_gpg_command\"\n ]\n },\n {\n \"name\": \"__fish_complete_gpg_key_id\",\n \"file\": \"$__fish_data_dir/functions/__fish_complete_gpg_key_id.fish\",\n \"flags\": [\n \"-d Complete using gpg key ids\",\n \"-a __fish_complete_gpg_command\"\n ],\n \"description\": \"Complete using gpg key ids\"\n },\n {\n \"name\": \"__fish_complete_gpg_user_id\",\n \"file\": \"$__fish_data_dir/functions/__fish_complete_gpg_user_id.fish\",\n \"flags\": [\n \"-d Complete using gpg user ids\",\n \"-a __fish_complete_gpg_command\"\n ],\n \"description\": \"Complete using gpg user ids\"\n },\n {\n \"name\": \"__fish_complete_group_ids\",\n \"file\": \"$__fish_data_dir/functions/__fish_complete_group_ids.fish\",\n \"flags\": [\n \"--description Complete group IDs with group name as description\"\n ],\n \"description\": \"Complete group IDs with group name as description\"\n },\n {\n \"name\": \"__fish_complete_groups\",\n \"file\": \"$__fish_data_dir/functions/__fish_complete_groups.fish\",\n \"flags\": [\n \"--description Print a list of local groups, with group members as the description\"\n ],\n \"description\": \"Print a list of local groups, with group members as the description\"\n },\n {\n \"name\": \"__fish_complete_job_pids\",\n \"file\": \"$__fish_data_dir/functions/__fish_complete_job_pids.fish\",\n \"flags\": [\n \"--description Print a list of job PIDs and their commands\"\n ],\n \"description\": \"Print a list of job PIDs and their commands\"\n },\n {\n \"name\": \"__fish_complete_list\",\n \"file\": \"$__fish_data_dir/functions/__fish_complete_list.fish\",\n \"flags\": [\n \"--argument-names div\"\n ]\n },\n {\n \"name\": \"__fish_complete_lpr\",\n \"file\": \"$__fish_data_dir/functions/__fish_complete_lpr.fish\",\n \"flags\": [\n \"-d Complete lpr common options\",\n \"--argument-names cmd\"\n ],\n \"description\": \"Complete lpr common options\"\n },\n {\n \"name\": \"__fish_complete_lpr_option\",\n \"file\": \"$__fish_data_dir/functions/__fish_complete_lpr_option.fish\",\n \"flags\": [\n \"--description Complete lpr option\"\n ],\n \"description\": \"Complete lpr option\"\n },\n {\n \"name\": \"__fish_complete_magick\",\n \"file\": \"$__fish_data_dir/functions/__fish_complete_magick.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_complete_man\",\n \"file\": \"$__fish_data_dir/functions/__fish_complete_man.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_complete_netcat\",\n \"file\": \"$__fish_data_dir/functions/__fish_complete_netcat.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_complete_path\",\n \"file\": \"$__fish_data_dir/functions/__fish_complete_path.fish\",\n \"flags\": [\n \"--description Complete using path\"\n ],\n \"description\": \"Complete using path\"\n },\n {\n \"name\": \"__fish_complete_pg_database\",\n \"file\": \"$__fish_data_dir/functions/__fish_complete_pg_database.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_complete_pg_user\",\n \"file\": \"$__fish_data_dir/functions/__fish_complete_pg_user.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_complete_pgrep\",\n \"file\": \"$__fish_data_dir/functions/__fish_complete_pgrep.fish\",\n \"flags\": [\n \"-d Complete pgrep/pkill\",\n \"--argument-names cmd\"\n ],\n \"description\": \"Complete pgrep/pkill\"\n },\n {\n \"name\": \"__fish_complete_pids\",\n \"file\": \"$__fish_data_dir/functions/__fish_complete_pids.fish\",\n \"flags\": [\n \"-d Print a list of process identifiers along with brief descriptions\"\n ],\n \"description\": \"Print a list of process identifiers along with brief descriptions\"\n },\n {\n \"name\": \"__fish_complete_ppp_peer\",\n \"file\": \"$__fish_data_dir/functions/__fish_complete_ppp_peer.fish\",\n \"flags\": [\n \"--description Complete isp name for pon/poff\"\n ],\n \"description\": \"Complete isp name for pon/poff\"\n },\n {\n \"name\": \"__fish_complete_proc\",\n \"file\": \"$__fish_data_dir/functions/__fish_complete_proc.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_complete_ssh\",\n \"file\": \"$__fish_data_dir/functions/__fish_complete_ssh.fish\",\n \"flags\": [\n \"-d common completions for ssh commands\",\n \"--argument-names command\"\n ],\n \"description\": \"common completions for ssh commands\"\n },\n {\n \"name\": \"__fish_complete_subcommand\",\n \"file\": \"$__fish_data_dir/functions/__fish_complete_subcommand.fish\",\n \"flags\": [\n \"-d Complete subcommand\",\n \"--no-scope-shadowing\"\n ],\n \"description\": \"Complete subcommand\"\n },\n {\n \"name\": \"__fish_complete_suffix\",\n \"file\": \"$__fish_data_dir/functions/__fish_complete_suffix.fish\",\n \"flags\": [\n \"-d Complete using files\"\n ],\n \"description\": \"Complete using files\"\n },\n {\n \"name\": \"__fish_complete_user_at_hosts\",\n \"file\": \"$__fish_data_dir/functions/__fish_complete_user_at_hosts.fish\",\n \"flags\": [\n \"-d Print list host-names with user@\"\n ],\n \"description\": \"Print list host-names with user@\"\n },\n {\n \"name\": \"__fish_complete_user_ids\",\n \"file\": \"$__fish_data_dir/functions/__fish_complete_user_ids.fish\",\n \"flags\": [\n \"--description Complete user IDs with user name as description\"\n ],\n \"description\": \"Complete user IDs with user name as description\"\n },\n {\n \"name\": \"__fish_complete_users\",\n \"file\": \"$__fish_data_dir/functions/__fish_complete_users.fish\",\n \"flags\": [\n \"--description Print a list of local users, with the real user name as a description\"\n ],\n \"description\": \"Print a list of local users, with the real user name as a description\"\n },\n {\n \"name\": \"__fish_complete_zfs_mountpoint_properties\",\n \"file\": \"$__fish_data_dir/functions/__fish_complete_zfs_mountpoint_properties.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_complete_zfs_pools\",\n \"file\": \"$__fish_data_dir/functions/__fish_complete_zfs_pools.fish\",\n \"flags\": [\n \"-d Completes with available ZFS pools\"\n ],\n \"description\": \"Completes with available ZFS pools\"\n },\n {\n \"name\": \"__fish_complete_zfs_ro_properties\",\n \"file\": \"$__fish_data_dir/functions/__fish_complete_zfs_ro_properties.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_complete_zfs_rw_properties\",\n \"file\": \"$__fish_data_dir/functions/__fish_complete_zfs_rw_properties.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_complete_zfs_write_once_properties\",\n \"file\": \"$__fish_data_dir/functions/__fish_complete_zfs_write_once_properties.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_concat_completions\",\n \"file\": \"$__fish_data_dir/functions/__fish_concat_completions.fish\",\n \"flags\": [\n \"-d Generate completions that are specified as comma-separated values from stdin source\"\n ],\n \"description\": \"Generate completions that are specified as comma-separated values from stdin source\"\n },\n {\n \"name\": \"__fish_config_interactive\",\n \"file\": \"$__fish_data_dir/functions/__fish_config_interactive.fish\",\n \"flags\": [\n \"-d Initializations that should be performed when entering interactive mode\"\n ],\n \"description\": \"Initializations that should be performed when entering interactive mode\"\n },\n {\n \"name\": \"__fish_contains_opt\",\n \"file\": \"$__fish_data_dir/functions/__fish_contains_opt.fish\",\n \"flags\": [\n \"-d Checks if a specific option has been given in the current commandline\"\n ],\n \"description\": \"Checks if a specific option has been given in the current commandline\"\n },\n {\n \"name\": \"__fish_crux_packages\",\n \"file\": \"$__fish_data_dir/functions/__fish_crux_packages.fish\",\n \"flags\": [\n \"-d Obtain a list of installed packages\"\n ],\n \"description\": \"Obtain a list of installed packages\"\n },\n {\n \"name\": \"__fish_cursor_konsole\",\n \"file\": \"$__fish_data_dir/functions/__fish_cursor_konsole.fish\",\n \"flags\": [\n \"-d Set cursor (konsole)\"\n ],\n \"description\": \"Set cursor (konsole)\"\n },\n {\n \"name\": \"__fish_cursor_xterm\",\n \"file\": \"$__fish_data_dir/functions/__fish_cursor_xterm.fish\",\n \"flags\": [\n \"-d Set cursor (xterm)\"\n ],\n \"description\": \"Set cursor (xterm)\"\n },\n {\n \"name\": \"__fish_default_command_not_found_handler\",\n \"file\": \"$__fish_data_dir/functions/fish_command_not_found.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_describe_command\",\n \"file\": \"$__fish_data_dir/functions/__fish_describe_command.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_echo\",\n \"file\": \"$__fish_data_dir/functions/__fish_echo.fish\",\n \"flags\": [\n \"--inherit-variable erase_line\",\n \"--description run the given command after the current commandline and redraw the prompt\"\n ],\n \"description\": \"run the given command after the current commandline and redraw the prompt\"\n },\n {\n \"name\": \"__fish_edit_command_if_at_cursor\",\n \"file\": \"$__fish_data_dir/functions/__fish_edit_command_if_at_cursor.fish\",\n \"flags\": [\n \"--description If cursor is at the command token, edit the command source file\"\n ],\n \"description\": \"If cursor is at the command token, edit the command source file\"\n },\n {\n \"name\": \"__fish_first_token\",\n \"file\": \"$__fish_data_dir/functions/__fish_first_token.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_git_prompt\",\n \"file\": \"$__fish_data_dir/functions/__fish_git_prompt.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_git_prompt_show_upstream\",\n \"file\": \"$__fish_data_dir/functions/fish_git_prompt.fish\",\n \"flags\": [\n \"--description Helper function for fish_git_prompt\"\n ],\n \"description\": \"Helper function for fish_git_prompt\"\n },\n {\n \"name\": \"__fish_gnu_complete\",\n \"file\": \"$__fish_data_dir/functions/__fish_gnu_complete.fish\",\n \"flags\": [\n \"-d Wrapper for the complete built-in. Skips the long completions on non-GNU systems\"\n ],\n \"description\": \"Wrapper for the complete built-in. Skips the long completions on non-GNU systems\"\n },\n {\n \"name\": \"__fish_hg_prompt\",\n \"file\": \"$__fish_data_dir/functions/__fish_hg_prompt.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_indent\",\n \"file\": \"$__fish_data_dir/functions/__fish_indent.fish\",\n \"flags\": [\n \"--wraps fish_indent\",\n \"--inherit-variable dir\"\n ]\n },\n {\n \"name\": \"__fish_is_first_arg\",\n \"file\": \"$__fish_data_dir/functions/__fish_is_first_arg.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_is_first_token\",\n \"file\": \"$__fish_data_dir/functions/__fish_is_first_token.fish\",\n \"flags\": [\n \"-d Test if no non-switch argument has been specified yet\"\n ],\n \"description\": \"Test if no non-switch argument has been specified yet\"\n },\n {\n \"name\": \"__fish_is_git_repository\",\n \"file\": \"$__fish_data_dir/functions/__fish_is_git_repository.fish\",\n \"flags\": [\n \"--description Check if the current directory is a git repository\"\n ],\n \"description\": \"Check if the current directory is a git repository\"\n },\n {\n \"name\": \"__fish_is_nth_token\",\n \"file\": \"$__fish_data_dir/functions/__fish_is_nth_token.fish\",\n \"flags\": [\n \"--description Test if current token is the Nth (ignoring command and switches/flags)\",\n \"--argument-names n\"\n ],\n \"description\": \"Test if current token is the Nth (ignoring command and switches/flags)\"\n },\n {\n \"name\": \"__fish_is_switch\",\n \"file\": \"$__fish_data_dir/functions/__fish_is_switch.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_is_token_n\",\n \"file\": \"$__fish_data_dir/functions/__fish_is_token_n.fish\",\n \"flags\": [\n \"--description Test if current token is on Nth place\",\n \"--argument-names n\"\n ],\n \"description\": \"Test if current token is on Nth place\"\n },\n {\n \"name\": \"__fish_is_zfs_feature_enabled\",\n \"file\": \"$__fish_data_dir/functions/__fish_is_zfs_feature_enabled.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_list_current_token\",\n \"file\": \"$__fish_data_dir/functions/__fish_list_current_token.fish\",\n \"flags\": [\n \"-d List contents of token under the cursor if it is a directory, otherwise list the contents of the current directory\"\n ],\n \"description\": \"List contents of token under the cursor if it is a directory, otherwise list the contents of the current directory\"\n },\n {\n \"name\": \"__fish_make_cache_dir\",\n \"file\": \"$__fish_data_dir/functions/__fish_make_cache_dir.fish\",\n \"flags\": [\n \"--description Create and return XDG_CACHE_HOME\"\n ],\n \"description\": \"Create and return XDG_CACHE_HOME\"\n },\n {\n \"name\": \"__fish_make_completion_signals\",\n \"file\": \"$__fish_data_dir/functions/__fish_make_completion_signals.fish\",\n \"flags\": [\n \"--description Make list of kill signals for completion\"\n ],\n \"description\": \"Make list of kill signals for completion\"\n },\n {\n \"name\": \"__fish_man_page\",\n \"file\": \"$__fish_data_dir/functions/__fish_man_page.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_md5\",\n \"file\": \"$__fish_data_dir/functions/__fish_md5.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_mktemp_relative\",\n \"file\": \"$__fish_data_dir/functions/__fish_mktemp_relative.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_move_last\",\n \"file\": \"$__fish_data_dir/functions/__fish_move_last.fish\",\n \"flags\": [\n \"-d Move the last element of a directory history from src to dest\"\n ],\n \"description\": \"Move the last element of a directory history from src to dest\"\n },\n {\n \"name\": \"__fish_mysql_query\",\n \"file\": \"$__fish_data_dir/functions/__fish_complete_mysql.fish\",\n \"flags\": [\n \"-a query\"\n ]\n },\n {\n \"name\": \"__fish_no_arguments\",\n \"file\": \"$__fish_data_dir/functions/__fish_no_arguments.fish\",\n \"flags\": [\n \"-d Internal fish function\"\n ],\n \"description\": \"Internal fish function\"\n },\n {\n \"name\": \"__fish_not_contain_opt\",\n \"file\": \"$__fish_data_dir/functions/__fish_not_contain_opt.fish\",\n \"flags\": [\n \"-d Checks that a specific option is not in the current command line\"\n ],\n \"description\": \"Checks that a specific option is not in the current command line\"\n },\n {\n \"name\": \"__fish_nth_token\",\n \"file\": \"$__fish_data_dir/functions/__fish_nth_token.fish\",\n \"flags\": [\n \"--description Prints the Nth token (ignoring command and switches/flags)\",\n \"--argument-names n\"\n ],\n \"description\": \"Prints the Nth token (ignoring command and switches/flags)\"\n },\n {\n \"name\": \"__fish_number_of_cmd_args_wo_opts\",\n \"file\": \"$__fish_data_dir/functions/__fish_number_of_cmd_args_wo_opts.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_opt_validate_args\",\n \"file\": \"$__fish_data_dir/functions/fish_opt.fish\",\n \"flags\": [\n \"--no-scope-shadowing\"\n ]\n },\n {\n \"name\": \"__fish_paginate\",\n \"file\": \"$__fish_data_dir/functions/__fish_paginate.fish\",\n \"flags\": [\n \"-d Paginate the current command using the users default pager\"\n ],\n \"description\": \"Paginate the current command using the users default pager\"\n },\n {\n \"name\": \"__fish_parent_directories\",\n \"file\": \"$__fish_data_dir/functions/__fish_parent_directories.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_paste\",\n \"file\": \"$__fish_data_dir/functions/__fish_paste.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_prepend_sudo\",\n \"file\": \"$__fish_data_dir/functions/__fish_prepend_sudo.fish\",\n \"flags\": [\n \"-d DEPRECATED: use fish_commandline_prepend instead. Prepend 'sudo ' to the beginning of the current commandline\"\n ],\n \"description\": \"DEPRECATED: use fish_commandline_prepend instead. Prepend 'sudo ' to the beginning of the current commandline\"\n },\n {\n \"name\": \"__fish_prev_arg_in\",\n \"file\": \"$__fish_data_dir/functions/__fish_prev_arg_in.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_preview_current_file\",\n \"file\": \"$__fish_data_dir/functions/__fish_preview_current_file.fish\",\n \"flags\": [\n \"--description Open the file at the cursor in a pager\"\n ],\n \"description\": \"Open the file at the cursor in a pager\"\n },\n {\n \"name\": \"__fish_print_addresses\",\n \"file\": \"$__fish_data_dir/functions/__fish_print_addresses.fish\",\n \"flags\": [\n \"--description List own network addresses with interface as description\"\n ],\n \"description\": \"List own network addresses with interface as description\"\n },\n {\n \"name\": \"__fish_print_apt_packages\",\n \"file\": \"$__fish_data_dir/functions/__fish_print_apt_packages.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_print_cmd_args\",\n \"file\": \"$__fish_data_dir/functions/__fish_print_cmd_args.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_print_cmd_args_without_options\",\n \"file\": \"$__fish_data_dir/functions/__fish_print_cmd_args_without_options.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_print_commands\",\n \"file\": \"$__fish_data_dir/functions/__fish_print_commands.fish\",\n \"flags\": [\n \"--description Print a list of documented fish commands\"\n ],\n \"description\": \"Print a list of documented fish commands\"\n },\n {\n \"name\": \"__fish_print_debian_apache_confs\",\n \"file\": \"$__fish_data_dir/functions/__fish_print_debian_apache_confs.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_print_debian_apache_mods\",\n \"file\": \"$__fish_data_dir/functions/__fish_print_debian_apache_mods.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_print_debian_apache_sites\",\n \"file\": \"$__fish_data_dir/functions/__fish_print_debian_apache_sites.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_print_encodings\",\n \"file\": \"$__fish_data_dir/functions/__fish_print_encodings.fish\",\n \"flags\": [\n \"-d Complete using available character encodings\"\n ],\n \"description\": \"Complete using available character encodings\"\n },\n {\n \"name\": \"__fish_print_eopkg_packages\",\n \"file\": \"$__fish_data_dir/functions/__fish_print_eopkg_packages.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_print_filesystems\",\n \"file\": \"$__fish_data_dir/functions/__fish_print_filesystems.fish\",\n \"flags\": [\n \"-d Print a list of all known filesystem types\"\n ],\n \"description\": \"Print a list of all known filesystem types\"\n },\n {\n \"name\": \"__fish_print_gpg_algo\",\n \"file\": \"$__fish_data_dir/functions/__fish_print_gpg_algo.fish\",\n \"flags\": [\n \"-d Complete using all algorithms of the type specified in argv[2] supported by gpg. argv[2] is a regexp\",\n \"-a __fish_complete_gpg_command\"\n ],\n \"description\": \"Complete using all algorithms of the type specified in argv[2] supported by gpg. argv[2] is a regexp\"\n },\n {\n \"name\": \"__fish_print_groups\",\n \"file\": \"$__fish_data_dir/functions/__fish_print_groups.fish\",\n \"flags\": [\n \"--description Print a list of local groups\"\n ],\n \"description\": \"Print a list of local groups\"\n },\n {\n \"name\": \"__fish_print_help\",\n \"file\": \"$__fish_data_dir/functions/__fish_print_help.fish\",\n \"flags\": [\n \"--description Print help for the specified fish function or builtin\"\n ],\n \"description\": \"Print help for the specified fish function or builtin\"\n },\n {\n \"name\": \"__fish_print_hostnames\",\n \"file\": \"$__fish_data_dir/functions/__fish_print_hostnames.fish\",\n \"flags\": [\n \"-d Print a list of known hostnames\"\n ],\n \"description\": \"Print a list of known hostnames\"\n },\n {\n \"name\": \"__fish_print_interfaces\",\n \"file\": \"$__fish_data_dir/functions/__fish_print_interfaces.fish\",\n \"flags\": [\n \"--description Print a list of known network interfaces\"\n ],\n \"description\": \"Print a list of known network interfaces\"\n },\n {\n \"name\": \"__fish_print_lpr_options\",\n \"file\": \"$__fish_data_dir/functions/__fish_print_lpr_options.fish\",\n \"flags\": [\n \"--description Print lpr options\"\n ],\n \"description\": \"Print lpr options\"\n },\n {\n \"name\": \"__fish_print_lpr_printers\",\n \"file\": \"$__fish_data_dir/functions/__fish_print_lpr_printers.fish\",\n \"flags\": [\n \"--description Print lpr printers\"\n ],\n \"description\": \"Print lpr printers\"\n },\n {\n \"name\": \"__fish_print_modules\",\n \"file\": \"$__fish_data_dir/functions/__fish_print_modules.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_print_mounted\",\n \"file\": \"$__fish_data_dir/functions/__fish_print_mounted.fish\",\n \"flags\": [\n \"--description Print mounted devices\"\n ],\n \"description\": \"Print mounted devices\"\n },\n {\n \"name\": \"__fish_print_opkg_packages\",\n \"file\": \"$__fish_data_dir/functions/__fish_print_opkg_packages.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_print_packages\",\n \"file\": \"$__fish_data_dir/functions/__fish_print_packages.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_print_pacman_packages\",\n \"file\": \"$__fish_data_dir/functions/__fish_print_pacman_packages.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_print_pacman_repos\",\n \"file\": \"$__fish_data_dir/functions/__fish_print_pacman_repos.fish\",\n \"flags\": [\n \"--description Print the repositories configured for arch's pacman package manager\"\n ],\n \"description\": \"Print the repositories configured for arch's pacman package manager\"\n },\n {\n \"name\": \"__fish_print_pipestatus\",\n \"file\": \"$__fish_data_dir/functions/__fish_print_pipestatus.fish\",\n \"flags\": [\n \"--description Print pipestatus for prompt\"\n ],\n \"description\": \"Print pipestatus for prompt\"\n },\n {\n \"name\": \"__fish_print_pkg_add_packages\",\n \"file\": \"$__fish_data_dir/functions/__fish_print_pkg_add_packages.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_print_pkg_packages\",\n \"file\": \"$__fish_data_dir/functions/__fish_print_pkg_packages.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_print_port_packages\",\n \"file\": \"$__fish_data_dir/functions/__fish_print_port_packages.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_print_portage_available_pkgs\",\n \"file\": \"$__fish_data_dir/functions/__fish_print_portage_available_pkgs.fish\",\n \"flags\": [\n \"--description Print all available packages\"\n ],\n \"description\": \"Print all available packages\"\n },\n {\n \"name\": \"__fish_print_portage_installed_pkgs\",\n \"file\": \"$__fish_data_dir/functions/__fish_print_portage_installed_pkgs.fish\",\n \"flags\": [\n \"--description Print all installed packages (non-deduplicated)\"\n ],\n \"description\": \"Print all installed packages (non-deduplicated)\"\n },\n {\n \"name\": \"__fish_print_portage_packages\",\n \"file\": \"$__fish_data_dir/functions/__fish_print_portage_packages.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_print_portage_repository_paths\",\n \"file\": \"$__fish_data_dir/functions/__fish_print_portage_repository_paths.fish\",\n \"flags\": [\n \"--description Print the paths of all configured repositories\"\n ],\n \"description\": \"Print the paths of all configured repositories\"\n },\n {\n \"name\": \"__fish_print_rpm_packages\",\n \"file\": \"$__fish_data_dir/functions/__fish_print_rpm_packages.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_print_service_names\",\n \"file\": \"$__fish_data_dir/functions/__fish_print_service_names.fish\",\n \"flags\": [\n \"-d All services known to the system\"\n ],\n \"description\": \"All services known to the system\"\n },\n {\n \"name\": \"__fish_print_svn_rev\",\n \"file\": \"$__fish_data_dir/functions/__fish_print_svn_rev.fish\",\n \"flags\": [\n \"--description Print svn revisions\"\n ],\n \"description\": \"Print svn revisions\"\n },\n {\n \"name\": \"__fish_print_user_ids\",\n \"file\": \"$__fish_data_dir/functions/__fish_complete_mount_opts.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_print_users\",\n \"file\": \"$__fish_data_dir/functions/__fish_print_users.fish\",\n \"flags\": [\n \"--description Print a list of local users\"\n ],\n \"description\": \"Print a list of local users\"\n },\n {\n \"name\": \"__fish_print_VBox_vms\",\n \"file\": \"$__fish_data_dir/functions/__fish_print_VBox_vms.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_print_windows_drives\",\n \"file\": \"$__fish_data_dir/functions/__fish_print_windows_drives.fish\",\n \"flags\": [\n \"--description Print Windows drives\"\n ],\n \"description\": \"Print Windows drives\"\n },\n {\n \"name\": \"__fish_print_windows_users\",\n \"file\": \"$__fish_data_dir/functions/__fish_print_windows_users.fish\",\n \"flags\": [\n \"--description Print Windows user names\"\n ],\n \"description\": \"Print Windows user names\"\n },\n {\n \"name\": \"__fish_print_xbps_packages\",\n \"file\": \"$__fish_data_dir/functions/__fish_print_xbps_packages.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_print_xdg_applications_directories\",\n \"file\": \"$__fish_data_dir/functions/__fish_print_xdg_applications_directories.fish\",\n \"flags\": [\n \"--description Print directories where desktop files are stored\"\n ],\n \"description\": \"Print directories where desktop files are stored\"\n },\n {\n \"name\": \"__fish_print_xdg_mimetypes\",\n \"file\": \"$__fish_data_dir/functions/__fish_print_xdg_mimetypes.fish\",\n \"flags\": [\n \"--description Print XDG mime types\"\n ],\n \"description\": \"Print XDG mime types\"\n },\n {\n \"name\": \"__fish_print_xwindows\",\n \"file\": \"$__fish_data_dir/functions/__fish_print_xwindows.fish\",\n \"flags\": [\n \"--description Print X windows\"\n ],\n \"description\": \"Print X windows\"\n },\n {\n \"name\": \"__fish_print_zfs_snapshots\",\n \"file\": \"$__fish_data_dir/functions/__fish_print_zfs_snapshots.fish\",\n \"flags\": [\n \"-d Lists ZFS snapshots\"\n ],\n \"description\": \"Lists ZFS snapshots\"\n },\n {\n \"name\": \"__fish_protontricks_complete_appid\",\n \"file\": \"$__fish_data_dir/functions/__fish_protontricks_complete_appid.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_ps\",\n \"file\": \"$__fish_data_dir/functions/__fish_ps.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_pwd\",\n \"file\": \"$__fish_data_dir/functions/__fish_pwd.fish\",\n \"flags\": [\n \"--description Show current path\"\n ],\n \"description\": \"Show current path\"\n },\n {\n \"name\": \"__fish_reg__complete_keys\",\n \"file\": \"$__fish_data_dir/functions/__fish_reg__complete_keys.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_seen_argument\",\n \"file\": \"$__fish_data_dir/functions/__fish_seen_argument.fish\",\n \"flags\": [\n \"--description Check whether argument is used\"\n ],\n \"description\": \"Check whether argument is used\"\n },\n {\n \"name\": \"__fish_seen_subcommand_from\",\n \"file\": \"$__fish_data_dir/functions/__fish_seen_subcommand_from.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_set_locale\",\n \"file\": \"$__fish_data_dir/functions/__fish_set_locale.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_shared_key_bindings\",\n \"file\": \"$__fish_data_dir/functions/__fish_shared_key_bindings.fish\",\n \"flags\": [\n \"-d Bindings shared between emacs and vi mode\"\n ],\n \"description\": \"Bindings shared between emacs and vi mode\"\n },\n {\n \"name\": \"__fish_should_complete_switches\",\n \"file\": \"$__fish_data_dir/functions/__fish_should_complete_switches.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_svn_prompt\",\n \"file\": \"$__fish_data_dir/functions/__fish_svn_prompt.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_svn_prompt_parse_status\",\n \"file\": \"$__fish_data_dir/functions/fish_svn_prompt.fish\",\n \"flags\": [\n \"--description helper function that does pretty formatting on svn status\"\n ],\n \"description\": \"helper function that does pretty formatting on svn status\"\n },\n {\n \"name\": \"__fish_systemctl\",\n \"file\": \"$__fish_data_dir/functions/__fish_systemctl.fish\",\n \"flags\": [\n \"--description Call systemctl with some options from the current commandline\"\n ],\n \"description\": \"Call systemctl with some options from the current commandline\"\n },\n {\n \"name\": \"__fish_systemctl_services\",\n \"file\": \"$__fish_data_dir/functions/__fish_systemctl_services.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_systemd_machine_images\",\n \"file\": \"$__fish_data_dir/functions/__fish_systemd_machine_images.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_systemd_machines\",\n \"file\": \"$__fish_data_dir/functions/__fish_systemd_machines.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_toggle_comment_commandline\",\n \"file\": \"$__fish_data_dir/functions/__fish_toggle_comment_commandline.fish\",\n \"flags\": [\n \"--description Comment/uncomment the current command\"\n ],\n \"description\": \"Comment/uncomment the current command\"\n },\n {\n \"name\": \"__fish_tokenizer_state\",\n \"file\": \"$__fish_data_dir/functions/__fish_tokenizer_state.fish\",\n \"flags\": [\n \"--description Print the state of the tokenizer at the end of the given string\"\n ],\n \"description\": \"Print the state of the tokenizer at the end of the given string\"\n },\n {\n \"name\": \"__fish_umask_add\",\n \"file\": \"$__fish_data_dir/functions/umask.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_uname\",\n \"file\": \"$__fish_data_dir/functions/__fish_uname.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_use_subcommand\",\n \"file\": \"$__fish_data_dir/functions/__fish_use_subcommand.fish\",\n \"flags\": [\n \"-d Test if a non-switch argument has been given in the current commandline\"\n ],\n \"description\": \"Test if a non-switch argument has been given in the current commandline\"\n },\n {\n \"name\": \"__fish_vcs_prompt\",\n \"file\": \"$__fish_data_dir/functions/__fish_vcs_prompt.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_whatis\",\n \"file\": \"$__fish_data_dir/functions/__fish_whatis.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__fish_whatis_current_token\",\n \"file\": \"$__fish_data_dir/functions/__fish_whatis_current_token.fish\",\n \"flags\": [\n \"-d Show man page entries or function description related to the token under the cursor\"\n ],\n \"description\": \"Show man page entries or function description related to the token under the cursor\"\n },\n {\n \"name\": \"__fish_wireshark_choices\",\n \"file\": \"$__fish_data_dir/functions/__fish_complete_wireshark.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__npm_helper_installed\",\n \"file\": \"$__fish_data_dir/functions/__fish_npm_helper.fish\",\n \"flags\": []\n },\n {\n \"name\": \"__ssh_history_completions\",\n \"file\": \"$__fish_data_dir/functions/__ssh_history_completions.fish\",\n \"flags\": [\n \"-d Retrieve `user@host` entries from history\"\n ],\n \"description\": \"Retrieve `user@host` entries from history\"\n },\n {\n \"name\": \"__terlar_git_prompt\",\n \"file\": \"$__fish_data_dir/functions/__terlar_git_prompt.fish\",\n \"flags\": []\n },\n {\n \"name\": \"_validate_int\",\n \"file\": \"$__fish_data_dir/functions/_validate_int.fish\",\n \"flags\": [\n \"--no-scope-shadowing\"\n ]\n },\n {\n \"name\": \"alias\",\n \"file\": \"$__fish_data_dir/functions/alias.fish\",\n \"flags\": [\n \"--description Creates a function wrapping a command\"\n ],\n \"description\": \"Creates a function wrapping a command\"\n },\n {\n \"name\": \"cd\",\n \"file\": \"$__fish_data_dir/functions/cd.fish\",\n \"flags\": [\n \"--description Change directory\"\n ],\n \"description\": \"Change directory\"\n },\n {\n \"name\": \"cdh\",\n \"file\": \"$__fish_data_dir/functions/cdh.fish\",\n \"flags\": [\n \"--description Menu based cd command\"\n ],\n \"description\": \"Menu based cd command\"\n },\n {\n \"name\": \"contains_seq\",\n \"file\": \"$__fish_data_dir/functions/contains_seq.fish\",\n \"flags\": [\n \"--description Return true if array contains a sequence\"\n ],\n \"description\": \"Return true if array contains a sequence\"\n },\n {\n \"name\": \"diff\",\n \"file\": \"$__fish_data_dir/functions/diff.fish\",\n \"flags\": []\n },\n {\n \"name\": \"dirh\",\n \"file\": \"$__fish_data_dir/functions/dirh.fish\",\n \"flags\": [\n \"--description Print the current directory history (the prev and next lists)\"\n ],\n \"description\": \"Print the current directory history (the prev and next lists)\"\n },\n {\n \"name\": \"dirs\",\n \"file\": \"$__fish_data_dir/functions/dirs.fish\",\n \"flags\": [\n \"--description Print directory stack\"\n ],\n \"description\": \"Print directory stack\"\n },\n {\n \"name\": \"down-or-search\",\n \"file\": \"$__fish_data_dir/functions/down-or-search.fish\",\n \"flags\": [\n \"-d search forward or move down 1 line\"\n ],\n \"description\": \"search forward or move down 1 line\"\n },\n {\n \"name\": \"edit_command_buffer\",\n \"file\": \"$__fish_data_dir/functions/edit_command_buffer.fish\",\n \"flags\": [\n \"--description Edit the command buffer in an external editor\"\n ],\n \"description\": \"Edit the command buffer in an external editor\"\n },\n {\n \"name\": \"export\",\n \"file\": \"$__fish_data_dir/functions/export.fish\",\n \"flags\": [\n \"--description Set env variable. Alias for `set -gx` for bash compatibility.\"\n ],\n \"description\": \"Set env variable. Alias for `set -gx` for bash compatibility.\"\n },\n {\n \"name\": \"fish_add_path\",\n \"file\": \"$__fish_data_dir/functions/fish_add_path.fish\",\n \"flags\": [\n \"--description Add paths to the PATH\"\n ],\n \"description\": \"Add paths to the PATH\"\n },\n {\n \"name\": \"fish_breakpoint_prompt\",\n \"file\": \"$__fish_data_dir/functions/fish_breakpoint_prompt.fish\",\n \"flags\": [\n \"--description A right prompt to be used when `breakpoint` is executed\"\n ],\n \"description\": \"A right prompt to be used when `breakpoint` is executed\"\n },\n {\n \"name\": \"fish_clipboard_copy\",\n \"file\": \"$__fish_data_dir/functions/fish_clipboard_copy.fish\",\n \"flags\": []\n },\n {\n \"name\": \"fish_clipboard_paste\",\n \"file\": \"$__fish_data_dir/functions/fish_clipboard_paste.fish\",\n \"flags\": []\n },\n {\n \"name\": \"fish_commandline_append\",\n \"file\": \"$__fish_data_dir/functions/fish_commandline_append.fish\",\n \"flags\": [\n \"--description Append the given string to the command-line, or remove the suffix if already there\"\n ],\n \"description\": \"Append the given string to the command-line, or remove the suffix if already there\"\n },\n {\n \"name\": \"fish_commandline_prepend\",\n \"file\": \"$__fish_data_dir/functions/fish_commandline_prepend.fish\",\n \"flags\": [\n \"--description Prepend the given string to the command-line, or remove the prefix if already there\"\n ],\n \"description\": \"Prepend the given string to the command-line, or remove the prefix if already there\"\n },\n {\n \"name\": \"fish_config\",\n \"file\": \"$__fish_data_dir/functions/fish_config.fish\",\n \"flags\": [\n \"--description Launch fish's web based configuration\"\n ],\n \"description\": \"Launch fish's web based configuration\"\n },\n {\n \"name\": \"fish_default_key_bindings\",\n \"file\": \"$__fish_data_dir/functions/fish_default_key_bindings.fish\",\n \"flags\": [\n \"-d emacs-like key binds\"\n ],\n \"description\": \"emacs-like key binds\"\n },\n {\n \"name\": \"fish_default_mode_prompt\",\n \"file\": \"$__fish_data_dir/functions/fish_default_mode_prompt.fish\",\n \"flags\": [\n \"--description Display vi prompt mode\"\n ],\n \"description\": \"Display vi prompt mode\"\n },\n {\n \"name\": \"fish_delta\",\n \"file\": \"$__fish_data_dir/functions/fish_delta.fish\",\n \"flags\": []\n },\n {\n \"name\": \"fish_fossil_prompt\",\n \"file\": \"$__fish_data_dir/functions/fish_fossil_prompt.fish\",\n \"flags\": [\n \"--description Write out the fossil prompt\"\n ],\n \"description\": \"Write out the fossil prompt\"\n },\n {\n \"name\": \"fish_greeting\",\n \"file\": \"$__fish_data_dir/functions/fish_greeting.fish\",\n \"flags\": []\n },\n {\n \"name\": \"fish_hg_prompt\",\n \"file\": \"$__fish_data_dir/functions/fish_hg_prompt.fish\",\n \"flags\": [\n \"--description Write out the hg prompt\"\n ],\n \"description\": \"Write out the hg prompt\"\n },\n {\n \"name\": \"fish_hybrid_key_bindings\",\n \"file\": \"$__fish_data_dir/functions/fish_hybrid_key_bindings.fish\",\n \"flags\": [\n \"--description Vi-style bindings that inherit emacs-style bindings in all modes\"\n ],\n \"description\": \"Vi-style bindings that inherit emacs-style bindings in all modes\"\n },\n {\n \"name\": \"fish_is_root_user\",\n \"file\": \"$__fish_data_dir/functions/fish_is_root_user.fish\",\n \"flags\": [\n \"--description Check if the user is root\"\n ],\n \"description\": \"Check if the user is root\"\n },\n {\n \"name\": \"fish_jj_prompt\",\n \"file\": \"$__fish_data_dir/functions/fish_jj_prompt.fish\",\n \"flags\": []\n },\n {\n \"name\": \"fish_job_summary\",\n \"file\": \"$__fish_data_dir/functions/fish_job_summary.fish\",\n \"flags\": [\n \"-a job_id\"\n ]\n },\n {\n \"name\": \"fish_mode_prompt\",\n \"file\": \"$__fish_data_dir/functions/fish_mode_prompt.fish\",\n \"flags\": [\n \"--description Displays the current mode\"\n ],\n \"description\": \"Displays the current mode\"\n },\n {\n \"name\": \"fish_print_git_action\",\n \"file\": \"$__fish_data_dir/functions/fish_print_git_action.fish\",\n \"flags\": [\n \"--argument-names git_dir\"\n ]\n },\n {\n \"name\": \"fish_print_hg_root\",\n \"file\": \"$__fish_data_dir/functions/fish_print_hg_root.fish\",\n \"flags\": []\n },\n {\n \"name\": \"fish_prompt\",\n \"file\": \"$__fish_data_dir/functions/fish_prompt.fish\",\n \"flags\": [\n \"--description Write out the prompt\"\n ],\n \"description\": \"Write out the prompt\"\n },\n {\n \"name\": \"fish_status_to_signal\",\n \"file\": \"$__fish_data_dir/functions/fish_status_to_signal.fish\",\n \"flags\": [\n \"--description Convert exit code to signal name\"\n ],\n \"description\": \"Convert exit code to signal name\"\n },\n {\n \"name\": \"fish_title\",\n \"file\": \"$__fish_data_dir/functions/fish_title.fish\",\n \"flags\": []\n },\n {\n \"name\": \"fish_update_completions\",\n \"file\": \"$__fish_data_dir/functions/fish_update_completions.fish\",\n \"flags\": [\n \"--description Update man-page based completions\"\n ],\n \"description\": \"Update man-page based completions\"\n },\n {\n \"name\": \"fish_vcs_prompt\",\n \"file\": \"$__fish_data_dir/functions/fish_vcs_prompt.fish\",\n \"flags\": [\n \"--description Print all vcs prompts\"\n ],\n \"description\": \"Print all vcs prompts\"\n },\n {\n \"name\": \"fish_vi_cursor\",\n \"file\": \"$__fish_data_dir/functions/fish_vi_cursor.fish\",\n \"flags\": [\n \"-d Set cursor shape for different vi modes\"\n ],\n \"description\": \"Set cursor shape for different vi modes\"\n },\n {\n \"name\": \"fish_vi_inc_dec\",\n \"file\": \"$__fish_data_dir/functions/fish_vi_key_bindings.fish\",\n \"flags\": [\n \"--description increment or decrement the number below the cursor\"\n ],\n \"description\": \"increment or decrement the number below the cursor\"\n },\n {\n \"name\": \"funced\",\n \"file\": \"$__fish_data_dir/functions/funced.fish\",\n \"flags\": [\n \"--description Edit function definition\"\n ],\n \"description\": \"Edit function definition\"\n },\n {\n \"name\": \"funcsave\",\n \"file\": \"$__fish_data_dir/functions/funcsave.fish\",\n \"flags\": [\n \"--description Save the current definition of all specified functions to file\"\n ],\n \"description\": \"Save the current definition of all specified functions to file\"\n },\n {\n \"name\": \"grep\",\n \"file\": \"$__fish_data_dir/functions/grep.fish\",\n \"flags\": []\n },\n {\n \"name\": \"help\",\n \"file\": \"$__fish_data_dir/functions/help.fish\",\n \"flags\": [\n \"--description Show help for the fish shell\"\n ],\n \"description\": \"Show help for the fish shell\"\n },\n {\n \"name\": \"history\",\n \"file\": \"$__fish_data_dir/functions/history.fish\",\n \"flags\": [\n \"--description display or manipulate interactive command history\"\n ],\n \"description\": \"display or manipulate interactive command history\"\n },\n {\n \"name\": \"isatty\",\n \"file\": \"$__fish_data_dir/functions/isatty.fish\",\n \"flags\": [\n \"-d Tests if a file descriptor is a tty\"\n ],\n \"description\": \"Tests if a file descriptor is a tty\"\n },\n {\n \"name\": \"la\",\n \"file\": \"$__fish_data_dir/functions/la.fish\",\n \"flags\": [\n \"--wraps ls\",\n \"--description List contents of directory, including hidden files in directory using long format\"\n ],\n \"description\": \"List contents of directory, including hidden files in directory using long format\"\n },\n {\n \"name\": \"ll\",\n \"file\": \"$__fish_data_dir/functions/ll.fish\",\n \"flags\": [\n \"--wraps ls\",\n \"--description List contents of directory using long format\"\n ],\n \"description\": \"List contents of directory using long format\"\n },\n {\n \"name\": \"ls\",\n \"file\": \"$__fish_data_dir/functions/ls.fish\",\n \"flags\": []\n },\n {\n \"name\": \"man\",\n \"file\": \"$__fish_data_dir/functions/man.fish\",\n \"flags\": []\n },\n {\n \"name\": \"N_\",\n \"file\": \"$__fish_data_dir/functions/N_.fish\",\n \"flags\": []\n },\n {\n \"name\": \"nextd\",\n \"file\": \"$__fish_data_dir/functions/nextd.fish\",\n \"flags\": [\n \"--description Move forward in the directory history\"\n ],\n \"description\": \"Move forward in the directory history\"\n },\n {\n \"name\": \"nextd-or-forward-token\",\n \"file\": \"$__fish_data_dir/functions/nextd-or-forward-token.fish\",\n \"flags\": [\n \"--description If commandline is empty, run nextd; else move one argument to the right\"\n ],\n \"description\": \"If commandline is empty, run nextd; else move one argument to the right\"\n },\n {\n \"name\": \"open\",\n \"file\": \"$__fish_data_dir/functions/open.fish\",\n \"flags\": [\n \"--description Open file in default application\"\n ],\n \"description\": \"Open file in default application\"\n },\n {\n \"name\": \"popd\",\n \"file\": \"$__fish_data_dir/functions/popd.fish\",\n \"flags\": [\n \"--description Pop directory from the stack and cd to it\"\n ],\n \"description\": \"Pop directory from the stack and cd to it\"\n },\n {\n \"name\": \"prevd\",\n \"file\": \"$__fish_data_dir/functions/prevd.fish\",\n \"flags\": [\n \"--description Move back in the directory history\"\n ],\n \"description\": \"Move back in the directory history\"\n },\n {\n \"name\": \"prevd-or-backward-token\",\n \"file\": \"$__fish_data_dir/functions/prevd-or-backward-token.fish\",\n \"flags\": [\n \"--description If commandline is empty, run prevd; else move one argument to the left\"\n ],\n \"description\": \"If commandline is empty, run prevd; else move one argument to the left\"\n },\n {\n \"name\": \"prompt_hostname\",\n \"file\": \"$__fish_data_dir/functions/prompt_hostname.fish\",\n \"flags\": [\n \"--description short hostname for the prompt\"\n ],\n \"description\": \"short hostname for the prompt\"\n },\n {\n \"name\": \"prompt_login\",\n \"file\": \"$__fish_data_dir/functions/prompt_login.fish\",\n \"flags\": [\n \"--description display user name for the prompt\"\n ],\n \"description\": \"display user name for the prompt\"\n },\n {\n \"name\": \"prompt_pwd\",\n \"file\": \"$__fish_data_dir/functions/prompt_pwd.fish\",\n \"flags\": [\n \"--description short CWD for the prompt\"\n ],\n \"description\": \"short CWD for the prompt\"\n },\n {\n \"name\": \"psub\",\n \"file\": \"$__fish_data_dir/functions/psub.fish\",\n \"flags\": [\n \"--description Read from stdin into a file and output the filename. Remove the file when the command that called psub exits.\"\n ],\n \"description\": \"Read from stdin into a file and output the filename. Remove the file when the command that called psub exits.\"\n },\n {\n \"name\": \"pushd\",\n \"file\": \"$__fish_data_dir/functions/pushd.fish\",\n \"flags\": [\n \"--description Push directory to stack\"\n ],\n \"description\": \"Push directory to stack\"\n },\n {\n \"name\": \"realpath\",\n \"file\": \"$__fish_data_dir/functions/realpath.fish\",\n \"flags\": []\n },\n {\n \"name\": \"seq\",\n \"file\": \"$__fish_data_dir/functions/seq.fish\",\n \"flags\": []\n },\n {\n \"name\": \"setenv\",\n \"file\": \"$__fish_data_dir/functions/setenv.fish\",\n \"flags\": []\n },\n {\n \"name\": \"suspend\",\n \"file\": \"$__fish_data_dir/functions/suspend.fish\",\n \"flags\": [\n \"--description Suspend the current shell.\"\n ],\n \"description\": \"Suspend the current shell.\"\n },\n {\n \"name\": \"trap\",\n \"file\": \"$__fish_data_dir/functions/trap.fish\",\n \"flags\": [\n \"-d Perform an action when the shell receives a signal\"\n ],\n \"description\": \"Perform an action when the shell receives a signal\"\n },\n {\n \"name\": \"up-or-search\",\n \"file\": \"$__fish_data_dir/functions/up-or-search.fish\",\n \"flags\": [\n \"-d Search back or move cursor up 1 line\"\n ],\n \"description\": \"Search back or move cursor up 1 line\"\n },\n {\n \"name\": \"vared\",\n \"file\": \"$__fish_data_dir/functions/vared.fish\",\n \"flags\": [\n \"--description Edit variable value\"\n ],\n \"description\": \"Edit variable value\"\n }\n]"
},
{
"path": "src/snippets/helperCommands.json",
"content": "[\n {\n \"name\": \"_\",\n \"description\": \"call fish’s translations\"\n },\n {\n \"name\": \"abbr\",\n \"description\": \"manage fish abbreviations\"\n },\n {\n \"name\": \"alias\",\n \"description\": \"create a function\"\n },\n {\n \"name\": \"and\",\n \"description\": \"conditionally execute a command\"\n },\n {\n \"name\": \"argparse\",\n \"description\": \"parse options passed to a fish script or function\"\n },\n {\n \"name\": \"begin\",\n \"description\": \"start a new block of code\"\n },\n {\n \"name\": \"bg\",\n \"description\": \"send jobs to background\"\n },\n {\n \"name\": \"bind\",\n \"description\": \"handle fish key bindings\"\n },\n {\n \"name\": \"block\",\n \"description\": \"temporarily block delivery of events\"\n },\n {\n \"name\": \"break\",\n \"description\": \"stop the current inner loop\"\n },\n {\n \"name\": \"breakpoint\",\n \"description\": \"launch debug mode\"\n },\n {\n \"name\": \"builtin\",\n \"description\": \"run a builtin command\"\n },\n {\n \"name\": \"case\",\n \"description\": \"conditionally execute a block of commands\"\n },\n {\n \"name\": \"cd\",\n \"description\": \"change directory\"\n },\n {\n \"name\": \"cdh\",\n \"description\": \"change to a recently visited directory\"\n },\n {\n \"name\": \"command\",\n \"description\": \"run a program\"\n },\n {\n \"name\": \"commandline\",\n \"description\": \"set or get the current command line buffer\"\n },\n {\n \"name\": \"complete\",\n \"description\": \"edit command-specific tab-completions\"\n },\n {\n \"name\": \"contains\",\n \"description\": \"test if a word is present in a list\"\n },\n {\n \"name\": \"continue\",\n \"description\": \"skip the remainder of the current iteration of the current inner loop\"\n },\n {\n \"name\": \"count\",\n \"description\": \"count the number of elements of a list\"\n },\n {\n \"name\": \"dirh\",\n \"description\": \"print directory history\"\n },\n {\n \"name\": \"dirs\",\n \"description\": \"print directory stack\"\n },\n {\n \"name\": \"disown\",\n \"description\": \"remove a process from the list of jobs\"\n },\n {\n \"name\": \"echo\",\n \"description\": \"display a line of text\"\n },\n {\n \"name\": \"else\",\n \"description\": \"execute command if a condition is not met\"\n },\n {\n \"name\": \"emit\",\n \"description\": \"emit a generic event\"\n },\n {\n \"name\": \"end\",\n \"description\": \"end a block of commands\"\n },\n {\n \"name\": \"eval\",\n \"description\": \"evaluate the specified commands\"\n },\n {\n \"name\": \"exec\",\n \"description\": \"execute command in current process\"\n },\n {\n \"name\": \"exit\",\n \"description\": \"exit the shell\"\n },\n {\n \"name\": \"export\",\n \"description\": \"compatibility function for exporting variables\"\n },\n {\n \"name\": \"false\",\n \"description\": \"return an unsuccessful result\"\n },\n {\n \"name\": \"fg\",\n \"description\": \"bring job to foreground\"\n },\n {\n \"name\": \"fish\",\n \"description\": \"the friendly interactive shell\"\n },\n {\n \"name\": \"fish_add_path\",\n \"description\": \"add to the path\"\n },\n {\n \"name\": \"fish_breakpoint_prompt\",\n \"description\": \"define the prompt when stopped at a breakpoint\"\n },\n {\n \"name\": \"fish_clipboard_copy\",\n \"description\": \"copy text to the system’s clipboard\"\n },\n {\n \"name\": \"fish_clipboard_paste\",\n \"description\": \"get text from the system’s clipboard\"\n },\n {\n \"name\": \"fish_command_not_found\",\n \"description\": \"what to do when a command wasn’t found\"\n },\n {\n \"name\": \"fish_config\",\n \"description\": \"start the web-based configuration interface\"\n },\n {\n \"name\": \"fish_default_key_bindings\",\n \"description\": \"set emacs key bindings for fish\"\n },\n {\n \"name\": \"fish_delta\",\n \"description\": \"compare functions and completions to the default\"\n },\n {\n \"name\": \"fish_git_prompt\",\n \"description\": \"output git information for use in a prompt\"\n },\n {\n \"name\": \"fish_greeting\",\n \"description\": \"display a welcome message in interactive shells\"\n },\n {\n \"name\": \"fish_hg_prompt\",\n \"description\": \"output Mercurial information for use in a prompt\"\n },\n {\n \"name\": \"fish_indent\",\n \"description\": \"indenter and prettifier\"\n },\n {\n \"name\": \"fish_is_root_user\",\n \"description\": \"check if the current user is root\"\n },\n {\n \"name\": \"fish_key_reader\",\n \"description\": \"explore what characters keyboard keys send\"\n },\n {\n \"name\": \"fish_mode_prompt\",\n \"description\": \"define the appearance of the mode indicator\"\n },\n {\n \"name\": \"fish_opt\",\n \"description\": \"create an option specification for the argparse command\"\n },\n {\n \"name\": \"fish_prompt\",\n \"description\": \"define the appearance of the command line prompt\"\n },\n {\n \"name\": \"fish_right_prompt\",\n \"description\": \"define the appearance of the right-side command line prompt\"\n },\n {\n \"name\": \"fish_should_add_to_history\",\n \"description\": \"decide whether a command should be added to the history\"\n },\n {\n \"name\": \"fish_status_to_signal\",\n \"description\": \"convert exit codes to human-friendly signals\"\n },\n {\n \"name\": \"fish_svn_prompt\",\n \"description\": \"output Subversion information for use in a prompt\"\n },\n {\n \"name\": \"fish_tab_title\",\n \"description\": \"define the terminal tab’s title\"\n },\n {\n \"name\": \"fish_title\",\n \"description\": \"define the terminal’s title\"\n },\n {\n \"name\": \"fish_update_completions\",\n \"description\": \"update completions using manual pages\"\n },\n {\n \"name\": \"fish_vcs_prompt\",\n \"description\": \"output version control system information for use in a prompt\"\n },\n {\n \"name\": \"fish_vi_key_bindings\",\n \"description\": \"set vi key bindings for fish\"\n },\n {\n \"name\": \"for\",\n \"description\": \"perform a set of commands multiple times\"\n },\n {\n \"name\": \"funced\",\n \"description\": \"edit a function interactively\"\n },\n {\n \"name\": \"funcsave\",\n \"description\": \"save the definition of a function to the user’s autoload directory\"\n },\n {\n \"name\": \"function\",\n \"description\": \"create a function\"\n },\n {\n \"name\": \"functions\",\n \"description\": \"print or erase functions\"\n },\n {\n \"name\": \"help\",\n \"description\": \"display fish documentation\"\n },\n {\n \"name\": \"history\",\n \"description\": \"show and manipulate command history\"\n },\n {\n \"name\": \"if\",\n \"description\": \"conditionally execute a command\"\n },\n {\n \"name\": \"isatty\",\n \"description\": \"test if a file descriptor is a terminal\"\n },\n {\n \"name\": \"jobs\",\n \"description\": \"print currently running jobs\"\n },\n {\n \"name\": \"math\",\n \"description\": \"perform mathematics calculations\"\n },\n {\n \"name\": \"nextd\",\n \"description\": \"move forward through directory history\"\n },\n {\n \"name\": \"not\",\n \"description\": \"negate the exit status of a job\"\n },\n {\n \"name\": \"open\",\n \"description\": \"open file in its default application\"\n },\n {\n \"name\": \"or\",\n \"description\": \"conditionally execute a command\"\n },\n {\n \"name\": \"path\",\n \"description\": \"manipulate and check paths\"\n },\n {\n \"name\": \"popd\",\n \"description\": \"move through directory stack\"\n },\n {\n \"name\": \"prevd\",\n \"description\": \"move backward through directory history\"\n },\n {\n \"name\": \"printf\",\n \"description\": \"display text according to a format string\"\n },\n {\n \"name\": \"prompt_hostname\",\n \"description\": \"print the hostname, shortened for use in the prompt\"\n },\n {\n \"name\": \"prompt_login\",\n \"description\": \"describe the login suitable for prompt\"\n },\n {\n \"name\": \"prompt_pwd\",\n \"description\": \"print pwd suitable for prompt\"\n },\n {\n \"name\": \"psub\",\n \"description\": \"perform process substitution\"\n },\n {\n \"name\": \"pushd\",\n \"description\": \"push directory to directory stack\"\n },\n {\n \"name\": \"pwd\",\n \"description\": \"output the current working directory\"\n },\n {\n \"name\": \"random\",\n \"description\": \"generate random number\"\n },\n {\n \"name\": \"read\",\n \"description\": \"read line of input into variables\"\n },\n {\n \"name\": \"realpath\",\n \"description\": \"convert a path to an absolute path without symlinks\"\n },\n {\n \"name\": \"return\",\n \"description\": \"stop the current inner function\"\n },\n {\n \"name\": \"set\",\n \"description\": \"display and change shell variables\"\n },\n {\n \"name\": \"set_color\",\n \"description\": \"set the terminal color\"\n },\n {\n \"name\": \"source\",\n \"description\": \"evaluate contents of file\"\n },\n {\n \"name\": \"status\",\n \"description\": \"query fish runtime information\"\n },\n {\n \"name\": \"string\",\n \"description\": \"manipulate strings\"\n },\n {\n \"name\": \"string-collect\",\n \"description\": \"join strings into one\"\n },\n {\n \"name\": \"string-escape\",\n \"description\": \"escape special characters\"\n },\n {\n \"name\": \"string-join\",\n \"description\": \"join strings with delimiter\"\n },\n {\n \"name\": \"string-join0\",\n \"description\": \"join strings with zero bytes\"\n },\n {\n \"name\": \"string-length\",\n \"description\": \"print string lengths\"\n },\n {\n \"name\": \"string-lower\",\n \"description\": \"convert strings to lowercase\"\n },\n {\n \"name\": \"string-match\",\n \"description\": \"match substrings\"\n },\n {\n \"name\": \"string-pad\",\n \"description\": \"pad strings to a fixed width\"\n },\n {\n \"name\": \"string-repeat\",\n \"description\": \"multiply a string\"\n },\n {\n \"name\": \"string-replace\",\n \"description\": \"replace substrings\"\n },\n {\n \"name\": \"string-shorten\",\n \"description\": \"shorten strings to a width, with an ellipsis\"\n },\n {\n \"name\": \"string-split\",\n \"description\": \"split strings by delimiter\"\n },\n {\n \"name\": \"string-split0\",\n \"description\": \"split on zero bytes\"\n },\n {\n \"name\": \"string-sub\",\n \"description\": \"extract substrings\"\n },\n {\n \"name\": \"string-trim\",\n \"description\": \"remove trailing whitespace\"\n },\n {\n \"name\": \"string-unescape\",\n \"description\": \"expand escape sequences\"\n },\n {\n \"name\": \"string-upper\",\n \"description\": \"convert strings to uppercase\"\n },\n {\n \"name\": \"suspend\",\n \"description\": \"suspend the current shell\"\n },\n {\n \"name\": \"switch\",\n \"description\": \"conditionally execute a block of commands\"\n },\n {\n \"name\": \"test\",\n \"description\": \"perform tests on files and text\"\n },\n {\n \"name\": \"time\",\n \"description\": \"measure how long a command or block takes\"\n },\n {\n \"name\": \"trap\",\n \"description\": \"perform an action when the shell receives a signal\"\n },\n {\n \"name\": \"true\",\n \"description\": \"return a successful result\"\n },\n {\n \"name\": \"type\",\n \"description\": \"locate a command and describe its type\"\n },\n {\n \"name\": \"ulimit\",\n \"description\": \"set or get resource usage limits\"\n },\n {\n \"name\": \"umask\",\n \"description\": \"set or get the file creation mode mask\"\n },\n {\n \"name\": \"vared\",\n \"description\": \"interactively edit the value of an environment variable\"\n },\n {\n \"name\": \"wait\",\n \"description\": \"wait for jobs to complete\"\n },\n {\n \"name\": \"while\",\n \"description\": \"perform a set of commands multiple times\"\n }\n]"
},
{
"path": "src/snippets/localeVariables.json",
"content": "[\n{\n\t\"name\": \"LANG\",\n\t\"description\": \"This is the typical environment variable for specifying a locale. A user may set this variable to express the language they speak, their region, and a character encoding. The actual values are specific to their platform, except for special values like C or POSIX. The value of LANG is used for each category unless the variable for that category was set or LC_ALL is set. So typically you only need to set LANG.An example value might be en_US.UTF-8 for the american version of english and the UTF-8 encoding, or de_AT.UTF-8 for the austrian version of german and the UTF-8 encoding. Your operating system might have a locale command that you can call as locale -a to see a list of defined locales. A UTF-8 encoding is recommended.\"\n},\n{\n\t\"name\": \"LC_ALL\",\n\t\"description\": \"Overrides the LANG environment variable and the values of the other LC_* variables. If this is set, none of the other variables are used for anything. Usually the other variables should be used instead. Use LC_ALL only when you need to override something.\"\n},\n{\n\t\"name\": \"LC_COLLATE\",\n\t\"description\": \"This determines the rules about equivalence of cases and alphabetical ordering: collation.\"\n},\n{\n\t\"name\": \"LC_CTYPE\",\n\t\"description\": \"This determines classification rules, like if the type of character is an alpha, digit, and so on. Most importantly, it defines the text encoding - which numbers map to which characters. On modern systems, this should typically be something ending in “UTF-8”.\"\n},\n{\n\t\"name\": \"LC_MESSAGES\",\n\t\"description\": \"LC_MESSAGES determines the language in which messages are diisplayed.\"\n},\n{\n\t\"name\": \"LC_MONETARY\",\n\t\"description\": \"Determines currency, how it is formatted, and the symbols used.\"\n},\n{\n\t\"name\": \"LC_NUMERIC\",\n\t\"description\": \"Sets the locale for formatting numbers.\"\n},\n{\n\t\"name\": \"LC_TIME\",\n\t\"description\": \"Sets the locale for formatting dates and times.\"\n}\n]\n"
},
{
"path": "src/snippets/pipesAndRedirects.json",
"content": "[ \n {\n \"name\": \">\",\n \"description\" : \"To write standard output to a file, use >DESTINATION\"\n }, \n {\n \"name\": \">>\",\n \"description\" : \"To append standard output to a file, use >>DESTINATION\"\n },\n {\n \"name\": \"2>\",\n \"description\": \"To write standard error to a file, use 2>DESTINATION\"\n },\n {\n \"name\": \"2>>\",\n \"description\": \"To write append standard error to a file, use 2>>DESTINATION\"\n },\n {\n \"name\": \"<\",\n \"description\": \"To write standard input from a file, use ?\",\n \"description\": \"To not overwrite (“clobber”) an existing file, use >?DESTINATION or 2>?DESTINATION. This is known as the “noclobber” redirection.\"\n },\n {\n \"name\": \"1>?\", \n \"description\": \"To not overwrite (“clobber”) an existing file, use >?DESTINATION or 1>?DESTINATION. This is known as the “noclobber” redirection.\"\n },\n {\n \"name\": \"2>?\",\n \"description\": \"To not overwrite (“clobber”) an existing file, use >?DESTINATION or 2>?DESTINATION. This is known as the “noclobber” redirection\"\n },\n {\n \"name\": \"&-\",\n \"description\": \"An ampersand followed by a minus sign (&-). The file descriptor will be closed.\" \n },\n {\n \"name\": \"|\",\n \"description\": \"Pipe one stream with another. Usually standard output of one command will be piped to standard input of another. OUTPUT | INPUT\"\n },\n {\n \"name\": \"&\",\n \"description\": \"Disown output . OUTPUT &\"\n },\n {\n \"name\": \"&>\",\n \"description\": \"the redirection &> can be used to direct both stdout and stderr to the same destination\"\n },\n {\n \"name\": \"2>|\",\n \"description\": \"pipe a different output file descriptor by prepending its FD number and the output redirect symbol to the pipe\"\n },\n {\n \"name\": \"&|\",\n \"description\": \"the redirection &| can be used to direct both stdout and stderr to the same destination\"\n },\n {\n \"name\": \"2>&1\",\n \"description\": \"Redirect both stderr and stdout\"\n },\n {\n \"name\": \"&2\",\n \"description\": \"An ampersand (&) followed by the number of another file descriptor like &2 for standard error. The output will be written to the destination descriptor.\"\n },\n {\n \"name\": \">&2\",\n \"description\": \"When you say >&2, that will redirect stdout to where stderr is pointing to at that time.\"\n }\n]\n"
},
{
"path": "src/snippets/specialFishVariables.json",
"content": "[\n {\n \"name\": \"PATH\",\n \"description\": \"A list of directories in which to search for commands. This is a common unix variable also used by other tools.\"\n },\n {\n \"name\": \"CDPATH\",\n \"description\": \"A list of directories in which the cd builtin looks for a new directory.\"\n },\n {\n \"name\": \"fish_term24bit\",\n \"description\": \"If this is set to 1, fish will assume the terminal understands 24-bit RGB color sequences, and won’t translate them to the 256 or 16 color palette. This is often detected automatically.\"\n },\n {\n \"name\": \"fish_term256\",\n \"description\": \"If this is set to 1, fish will assume the terminal understands 256 colors, and won’t translate matching colors down to the 16 color palette. This is usually autodetected.\"\n },\n {\n \"name\": \"fish_ambiguous_width\",\n \"description\": \"controls the computed width of ambiguous-width characters. This should be set to 1 if your terminal renders these characters as single-width (typical), or 2 if double-width.\"\n },\n {\n \"name\": \"fish_emoji_width\",\n \"description\": \"controls whether fish assumes emoji render as 2 cells or 1 cell wide. This is necessary because the correct value changed from 1 to 2 in Unicode 9, and some terminals may not be aware. Set this if you see graphical glitching related to emoji (or other “special” characters). It should usually be auto-detected.\"\n },\n {\n \"name\": \"fish_autosuggestion_enabled\",\n \"description\": \"controls if Autosuggestions are enabled. Set it to 0 to disable, anything else to enable. By default they are on.\"\n },\n {\n \"name\": \"fish_handle_reflow\",\n \"description\": \"determines whether fish should try to repaint the commandline when the terminal resizes. In terminals that reflow text this should be disabled. Set it to 1 to enable, anything else to disable.\"\n },\n {\n \"name\": \"fish_key_bindings\",\n \"description\": \"the name of the function that sets up the keyboard shortcuts for the command-line editor.\"\n },\n {\n \"name\": \"fish_escape_delay_ms\",\n \"description\": \"sets how long fish waits for another key after seeing an escape, to distinguish pressing the escape key from the start of an escape sequence. The default is 30ms. Increasing it increases the latency but allows pressing escape instead of alt for alt+character bindings. For more information, see the chapter in the bind documentation.\"\n },\n {\n \"name\": \"fish_sequence_key_delay_ms\",\n \"description\": \"sets how long fish waits for another key after seeing a key that is part of a longer sequence, to disambiguate. For instance if you had bound \\\\cx\\\\ce to open an editor, fish would wait for this long in milliseconds to see a ctrl-e after a ctrl-x. If the time elapses, it will handle it as a ctrl-x (by default this would copy the current commandline to the clipboard). See also Key sequences.\"\n },\n {\n \"name\": \"fish_complete_path\",\n \"description\": \"determines where fish looks for completion. When trying to complete for a command, fish looks for files in the directories in this variable.\"\n },\n {\n \"name\": \"fish_cursor_selection_mode\",\n \"description\": \"controls whether the selection is inclusive or exclusive of the character under the cursor (see Copy and Paste).\"\n },\n {\n \"name\": \"fish_function_path\",\n \"description\": \"determines where fish looks for functions. When fish autoloads a function, it will look for files in these directories.\"\n },\n {\n \"name\": \"fish_greeting\",\n \"description\": \"the greeting message printed on startup. This is printed by a function of the same name that can be overridden for more complicated changes (see funced)\"\n },\n {\n \"name\": \"fish_history\",\n \"description\": \"the current history session name. If set, all subsequent commands within an interactive fish session will be logged to a separate file identified by the value of the variable. If unset, the default session name “fish” is used. If set to an empty string, history is not saved to disk (but is still available within the interactive session).\"\n },\n {\n \"name\": \"fish_trace\",\n \"description\": \"if set and not empty, will cause fish to print commands before they execute, similar to set -x in bash. The trace is printed to the path given by the --debug-output option to fish or the FISH_DEBUG_OUTPUT variable. It goes to stderr by default.\"\n },\n {\n \"name\": \"FISH_DEBUG\",\n \"description\": \"Controls which debug categories fish enables for output, analogous to the --debug option.\"\n },\n {\n \"name\": \"FISH_DEBUG_OUTPUT\",\n \"description\": \"Specifies a file to direct debug output to.\"\n },\n {\n \"name\": \"fish_user_paths\",\n \"description\": \"a list of directories that are prepended to PATH. This can be a universal variable.\"\n },\n {\n \"name\": \"umask\",\n \"description\": \"the current file creation mask. The preferred way to change the umask variable is through the umask function. An attempt to set umask to an invalid value will always fail.\"\n },\n {\n \"name\": \"BROWSER\",\n \"description\": \"your preferred web browser. If this variable is set, fish will use the specified browser instead of the system default browser to display the fish documentation.\"\n }\n]\n"
},
{
"path": "src/snippets/statusNumbers.json",
"content": "[\n {\n \"name\": \"0\",\n \"description\": \"0 is generally the exit status of commands if they successfully performed the requested operation.\"\n },\n {\n \"name\": \"1\",\n \"description\": \"1 is generally the exit status of commands if they failed to perform the requested operation.\"\n },\n {\n \"name\": \"121\",\n \"description\": \"121 is generally the exit status of commands if they were supplied with invalid arguments.\"\n },\n {\n \"name\": \"123\",\n \"description\": \"123 means that the command was not executed because the command name contained invalid characters.\"\n },\n {\n \"name\": \"124\",\n \"description\": \"124 means that the command was not executed because none of the wildcards in the command produced any matches.\"\n },\n {\n \"name\": \"125\",\n \"description\": \"125 means that while an executable with the specified name was located, the operating system could not actually execute the command.\"\n },\n {\n \"name\": \"126\",\n \"description\": \"126 means that while a file with the specified name was located, it was not executable.\"\n },\n {\n \"name\": \"127\",\n \"description\": \"127 means that no function, builtin or command with the given name could be located.\"\n },\n {\n \"name\": \"128\",\n \"description\": \"128 is used when a process exits a signal, plus the number of the signal\"\n }\n]"
},
{
"path": "src/snippets/syntaxHighlightingVariables.json",
"content": "[\n {\n \"name\": \"fish_color_normal\",\n \"description\": \"default color\"\n },\n {\n \"name\": \"fish_color_command\",\n \"description\": \"commands like echo\"\n },\n {\n \"name\": \"fish_color_keyword\",\n \"description\": \"keywords like if - this falls back on the command color if unset\"\n },\n {\n \"name\": \"fish_color_quote\",\n \"description\": \"quoted text like \\\"abc\\\"\"\n },\n {\n \"name\": \"fish_color_redirection\",\n \"description\": \"IO redirections like >/dev/null\"\n },\n {\n \"name\": \"fish_color_end\",\n \"description\": \"process separators like ; and &\"\n },\n {\n \"name\": \"fish_color_error\",\n \"description\": \"syntax errors\"\n },\n {\n \"name\": \"fish_color_param\",\n \"description\": \"ordinary command parameters\"\n },\n {\n \"name\": \"fish_color_valid_path\",\n \"description\": \"parameters that are filenames (if the file exists)\"\n },\n {\n \"name\": \"fish_color_option\",\n \"description\": \"options starting with “-”, up to the first “--” parameter\"\n },\n {\n \"name\": \"fish_color_comment\",\n \"description\": \"comments like ‘# important’\"\n },\n {\n \"name\": \"fish_color_selection\",\n \"description\": \"selected text in vi visual mode\"\n },\n {\n \"name\": \"fish_color_operator\",\n \"description\": \"parameter expansion operators like * and ~\"\n },\n {\n \"name\": \"fish_color_escape\",\n \"description\": \"character escapes like \\\\n and \\\\x70\"\n },\n {\n \"name\": \"fish_color_autosuggestion\",\n \"description\": \"autosuggestions (the proposed rest of a command)\"\n },\n {\n \"name\": \"fish_color_cwd\",\n \"description\": \"the current working directory in the default prompt\"\n },\n {\n \"name\": \"fish_color_cwd_root\",\n \"description\": \"the current working directory in the default prompt for the root user\"\n },\n {\n \"name\": \"fish_color_user\",\n \"description\": \"the username in the default prompt\"\n },\n {\n \"name\": \"fish_color_host\",\n \"description\": \"the hostname in the default prompt\"\n },\n {\n \"name\": \"fish_color_host_remote\",\n \"description\": \"the hostname in the default prompt for remote sessions (like ssh)\"\n },\n {\n \"name\": \"fish_color_status\",\n \"description\": \"the last command’s nonzero exit code in the default prompt\"\n },\n {\n \"name\": \"fish_color_cancel\",\n \"description\": \"the ‘^C’ indicator on a canceled command\"\n },\n {\n \"name\": \"fish_color_search_match\",\n \"description\": \"history search matches and selected pager items (background only)\"\n },\n {\n \"name\": \"fish_color_history_current\",\n \"description\": \"the current position in the history for commands like dirh and cdh\"\n },\n {\n \"name\": \"fish_pager_color_progress\",\n \"description\": \"the progress bar at the bottom left corner\"\n },\n {\n \"name\": \"fish_pager_color_background\",\n \"description\": \"the background color of a line\"\n },\n {\n \"name\": \"fish_pager_color_prefix\",\n \"description\": \"the prefix string, i.e. the string that is to be completed\"\n },\n {\n \"name\": \"fish_pager_color_completion\",\n \"description\": \"the completion itself, i.e. the proposed rest of the string\"\n },\n {\n \"name\": \"fish_pager_color_description\",\n \"description\": \"the completion description\"\n },\n {\n \"name\": \"fish_pager_color_selected_background\",\n \"description\": \"background of the selected completion\"\n },\n {\n \"name\": \"fish_pager_color_selected_prefix\",\n \"description\": \"prefix of the selected completion\"\n },\n {\n \"name\": \"fish_pager_color_selected_completion\",\n \"description\": \"suffix of the selected completion\"\n },\n {\n \"name\": \"fish_pager_color_selected_description\",\n \"description\": \"description of the selected completion\"\n },\n {\n \"name\": \"fish_pager_color_secondary_background\",\n \"description\": \"background of every second unselected completion\"\n },\n {\n \"name\": \"fish_pager_color_secondary_prefix\",\n \"description\": \"prefix of every second unselected completion\"\n },\n {\n \"name\": \"fish_pager_color_secondary_completion\",\n \"description\": \"suffix of every second unselected completion\"\n },\n {\n \"name\": \"fish_pager_color_secondary_description\",\n \"description\": \"description of every second unselected completion\"\n }\n]"
},
{
"path": "src/utils/builtins.ts",
"content": "import { spawnSync, SpawnSyncOptionsWithStringEncoding } from 'child_process';\n\nexport const BuiltInList = [\n '!',\n '.',\n ':',\n '[',\n '_',\n 'abbr',\n 'and',\n 'argparse',\n 'begin',\n 'bg',\n 'bind',\n 'block',\n 'break',\n 'breakpoint',\n 'builtin',\n 'case',\n 'cd',\n 'command',\n 'commandline',\n 'complete',\n 'contains',\n 'continue',\n 'count',\n 'disown',\n 'echo',\n 'else',\n 'emit',\n 'end',\n 'eval',\n 'exec',\n 'exit',\n 'false',\n 'fg',\n 'fish_indent',\n 'fish_key_reader',\n 'for',\n 'function',\n 'functions',\n 'history',\n 'if',\n 'jobs',\n 'math',\n 'not',\n 'or',\n 'path',\n 'printf',\n 'pwd',\n 'random',\n 'read',\n 'realpath',\n 'return',\n 'set',\n 'set_color',\n 'source',\n 'status',\n 'string',\n 'switch',\n 'test',\n 'time',\n 'true',\n 'type',\n 'ulimit',\n 'wait',\n 'while',\n];\n\n/**\n * You can generate this list by running `builtin --names` in a fish session\n * note that '.', and ':' are removed from the list because they do not contain\n * a man-page\n */\nconst BuiltInSET = new Set(BuiltInList);\n\n/**\n * check if string is one of the default fish builtin functions\n */\nexport function isBuiltin(word: string): boolean {\n return BuiltInSET.has(word);\n}\n\nconst reservedKeywords = [\n '[',\n '_',\n 'and',\n 'argparse',\n 'begin',\n 'break',\n 'builtin',\n 'case',\n 'command',\n 'continue',\n 'else',\n 'end',\n 'eval',\n 'exec',\n 'for',\n 'function',\n 'if',\n 'not',\n 'or',\n 'read',\n 'return',\n 'set',\n 'status',\n 'string',\n 'switch',\n 'test',\n 'time',\n 'and',\n 'while',\n];\nconst ReservedKeywordSet = new Set(reservedKeywords);\n\n/**\n * Reserved keywords are not allowed as function names.\n * Found on the `function` manpage.\n */\nexport function isReservedKeyword(word: string): boolean {\n return ReservedKeywordSet.has(word);\n}\n\n/**\n * Find the fish shell path using `which fish`\n */\nexport function findShell() {\n const result = spawnSync('which fish', { shell: true, stdio: ['ignore', 'pipe', 'inherit'], encoding: 'utf-8' });\n return result.stdout?.toString().trim() || 'fish';\n}\nconst fishShell = findShell();\n\nconst spawnOpts: SpawnSyncOptionsWithStringEncoding = {\n shell: fishShell,\n stdio: ['ignore', 'pipe', 'inherit'],\n encoding: 'utf-8',\n};\n\n/**\n * Helper function to safely execute fish commands and return output as lines.\n * Returns an empty array if stdout is not available or command fails.\n */\nfunction execFishCommand(command: string): string[] {\n const result = spawnSync(command, spawnOpts);\n return result.stdout?.toString().split('\\n') || [];\n}\n\nfunction createFunctionNamesList() {\n return execFishCommand('functions --names | string split -n \\'\\\\n\\'');\n}\nexport const FunctionNamesList = createFunctionNamesList();\nexport function isFunction(word: string): boolean {\n return FunctionNamesList.includes(word);\n}\nfunction createFunctionEventsList() {\n return execFishCommand('functions --handlers | string match -vr \\'^Event \\\\w+\\' | string split -n \\'\\\\n\\'');\n}\n\n/**\n * Consider using these utilities to check if a word is a event on a function/emit/trap\n */\nexport const EventNamesList = createFunctionEventsList();\nexport function isEvent(word: string): boolean {\n return EventNamesList.includes(word);\n}\n\nfunction createAbbrList() {\n return execFishCommand('abbr --show');\n}\nexport const AbbrList = createAbbrList();\n\nfunction createGlobalVariableList() {\n return execFishCommand('set -n');\n}\n\nexport const GlobalVariableList = createGlobalVariableList();\n\n/**\n * TO get the list of commands with potential subcommands, you can use:\n *\n * >_ cd /usr/share/fish/completions/\n * >_ for i in (rg -e '-a' -l); echo (string split -f 1 '.fish' -m1 $i);end\n *\n * example commands with potential subcommands\n * • string split ...\n * • killall node\n * • man vim\n * • command fish\n *\n * useful when checking the current Command for documentation/completion\n * suggestions. If a match is hit, check one more node back, and if it is\n * not a command, stop searching backwards.\n */\n\n// List of global aliases removed (check history if needed in future)\n"
},
{
"path": "src/utils/cli-dump-tree.ts",
"content": "import { LspDocument } from '../document';\nimport { Analyzer, analyzer } from '../analyze';\nimport { logger } from '../logger';\nimport { SyncFileHelper } from './file-operations';\nimport path from 'path';\nimport chalk from 'chalk';\nimport { CommanderSubcommand } from './commander-cli-subcommands';\nimport { semanticTokenHandler } from '../semantic-tokens';\nimport { FishSemanticTokens } from './semantics';\nimport { type FishSymbol, processNestedTree, formatFishSymbolTree } from '../parsing/symbol';\nimport { createInterface } from 'node:readline';\nimport { startServer } from './startup';\nimport * as os from 'os';\n\n/**\n * Checks whether a CLI dump flag value indicates stdin input.\n * Returns true when the flag is unset, boolean `true`, empty string, or `\"-\"`.\n */\nfunction isDumpFlagStdin(value: string | boolean | undefined): boolean {\n if (!value || value === true) return true;\n if (typeof value === 'string') {\n const trimmed = value.trim();\n return trimmed === '' || trimmed === '-';\n }\n return false;\n}\n\ninterface ParseTreeOutput {\n source: string;\n parseTree: string;\n}\n\ninterface SemanticTokensOutput {\n source: string;\n tokens: string;\n}\n\n/**\n * Reads all content from stdin, line by line.\n * It works for both piped input and manual terminal input.\n * @returns Promise - The content from stdin, or an empty string if there is no input.\n */\nasync function readFromStdin(): Promise {\n const rl = createInterface({\n input: process.stdin,\n terminal: false, // Set to false to avoid issues with piped input\n });\n\n let data = '';\n for await (const line of rl) {\n data += line + '\\n';\n }\n return data.trim(); // Trim trailing newline for cleaner output\n}\n\n/**\n * Debug utility that acts like tree-sitter-cli on a source file.\n * Shows both the raw source code and the tree-sitter parse tree.\n *\n * @param document - The LspDocument to debug\n * @returns Object containing both source and parse tree as strings\n */\nexport function debugWorkspaceDocument(document: LspDocument, useColors: boolean = true): ParseTreeOutput {\n const source = document.getText();\n\n // Parse the document using the existing analyzer's parser\n const tree = analyzer.parser.parse(source);\n\n // Convert the parse tree to a readable string format\n const parseTree = formatSyntaxTree(tree.rootNode, 0, useColors);\n\n return {\n source,\n parseTree,\n };\n}\n\n/**\n * Color scheme for different node types\n */\nconst nodeTypeColors = {\n // Fish-specific node types\n command: chalk.blue,\n command_name: chalk.blue.bold,\n argument: chalk.green,\n option: chalk.yellow,\n redirection: chalk.magenta,\n pipe: chalk.cyan,\n variable_expansion: chalk.red,\n variable_name: chalk.red.bold,\n string: chalk.green,\n quoted_string: chalk.green,\n double_quote_string: chalk.green,\n single_quote_string: chalk.green,\n concatenation: chalk.yellow,\n word: chalk.yellow,\n comment: chalk.yellow.dim,\n function_definition: chalk.blue.bold,\n if_statement: chalk.cyan.bold,\n for_statement: chalk.cyan.bold,\n while_statement: chalk.cyan.bold,\n switch_statement: chalk.cyan.bold,\n case_clause: chalk.cyan,\n begin_statement: chalk.magenta.bold,\n end: chalk.magenta.bold,\n program: chalk.white.bold,\n integer: chalk.yellow,\n float: chalk.yellow,\n boolean: chalk.yellow,\n identifier: chalk.white.bgBlack,\n ERROR: chalk.red.bold,\n // Symbols and operators\n '(': chalk.white.bold.italic,\n ')': chalk.white.bold.italic,\n '[': chalk.white.bold.italic,\n ']': chalk.white.bold.italic,\n '{': chalk.white.bold.italic,\n '}': chalk.white.bold.italic,\n '|': chalk.cyan.bold,\n '&&': chalk.cyan,\n '||': chalk.cyan,\n ';': chalk.white.bold.italic,\n '\\n': chalk.white.bold.italic,\n // Default fallback\n default: chalk.white.bgBlack,\n};\n\n/**\n * Color scheme for parentheses based on nesting depth\n */\nconst parenthesesColors = [\n chalk.white,\n chalk.yellow,\n chalk.cyan,\n chalk.magenta,\n chalk.green,\n chalk.blue,\n chalk.red,\n];\n\n/**\n * Get color function for a given node type\n */\nfunction getNodeTypeColor(nodeType: string): (text: string) => string {\n return nodeTypeColors[nodeType as keyof typeof nodeTypeColors] || nodeTypeColors.default;\n}\n\n/**\n * Get color function for parentheses based on depth\n */\nfunction getParenthesesColor(depth: number): (text: string) => string {\n return parenthesesColors[depth % parenthesesColors.length] || chalk.yellowBright;\n}\n\n/**\n * Recursively formats a syntax tree node into a readable string representation\n * similar to tree-sitter-cli output, with comprehensive color highlighting.\n */\nfunction formatSyntaxTree(node: any, depth: number = 0, useColors: boolean = true): string {\n const indent = ' '.repeat(depth);\n const rawNodeType = node.type || 'unknown';\n // If node type is just whitespace, escape it for visibility\n const nodeType = rawNodeType.trim() === '' ? escapeWhitespace(rawNodeType) : rawNodeType;\n const startPos = `${node.startPosition?.row || 0}:${node.startPosition?.column || 0}`;\n const endPos = `${node.endPosition?.row || 0}:${node.endPosition?.column || 0}`;\n\n // Get colors for this depth and node type (or no-op functions if colors disabled)\n const parenColor = useColors ? getParenthesesColor(depth) : (text: string) => text;\n const typeColor = useColors ? getNodeTypeColor(nodeType) : (text: string) => text;\n const rangeColor = useColors ? chalk.dim.white.dim : (text: string) => text;\n\n let result = `${indent}${parenColor('(')}${typeColor(nodeType)} ${rangeColor(`[${startPos}, ${endPos}]`)}`;\n\n // If it's a leaf node with text, show the text with proper escaping\n if (node.children.length === 0 && node.text) {\n const escapedText = escapeWhitespace(node.text);\n if (useColors) {\n result += ` ${chalk.dim('\"')}${chalk.italic.green(escapedText)}${chalk.dim('\"')}`;\n } else {\n result += ` \"${escapedText}\"`;\n }\n }\n\n // Handle children\n if (node.children.length > 0) {\n result += '\\n';\n // Recursively format children\n for (const child of node.children) {\n result += formatSyntaxTree(child, depth + 1, useColors);\n }\n result += `${indent}${parenColor(')')}`;\n } else {\n result += parenColor(')');\n }\n\n // Always end with a newline, regardless of whether this node has children\n result += '\\n';\n\n return result;\n}\n\n/**\n * Escapes whitespace characters in text for readable display\n * Uses JSON.stringify for proper escaping similar to tree-sitter-cli\n */\nfunction escapeWhitespace(text: string): string {\n // Use JSON.stringify to properly escape the string, then remove the outer quotes\n const escaped = JSON.stringify(text);\n return escaped.slice(1, -1); // Remove the surrounding quotes\n}\n\n/**\n * Pretty prints the debug output to console in a readable format.\n *\n * @param document - The LspDocument to debug\n */\nexport function logTreeSitterDocumentDebug(document: LspDocument): void {\n const { source, parseTree } = debugWorkspaceDocument(document);\n\n logger.log('='.repeat(80));\n logger.log(`DEBUG: ${document.getFileName()}`);\n logger.log('='.repeat(80));\n logger.log('SOURCE:');\n logger.log('-'.repeat(40));\n\n // Print source with line numbers\n const lines = source.split('\\n');\n lines.forEach((line, index) => {\n logger.log(`${(index + 1).toString().padStart(3)}: ${line}`);\n });\n\n logger.log('\\n' + '-'.repeat(40));\n logger.log('PARSE TREE:');\n logger.log('-'.repeat(40));\n logger.log(parseTree);\n logger.log('='.repeat(80));\n}\n\nexport function returnParseTreeString(document: LspDocument, useColors: boolean = true): string {\n const { parseTree } = debugWorkspaceDocument(document, useColors);\n return parseTree;\n}\n\nexport function expandParseCliTreeFile(input: string | undefined): string {\n if (!input || !input.trim()) {\n return '';\n }\n\n const resultPath = SyncFileHelper.expandEnvVars(input);\n if (SyncFileHelper.isAbsolutePath(resultPath)) {\n return resultPath;\n }\n return path.resolve(resultPath);\n}\n\nexport async function cliDumpParseTree(document: LspDocument, useColors: boolean = true): Promise<0 | 1> {\n await Analyzer.initialize();\n const { parseTree } = debugWorkspaceDocument(document, useColors);\n\n // Output the parse tree to stdout\n logger.logToStdout(parseTree);\n if (parseTree.trim().length === 0) {\n const errorMsg = useColors ? chalk.red('No parse tree available for this document.') : 'No parse tree available for this document.';\n logger.logToStderr(errorMsg);\n return 1;\n }\n return 0;\n}\n\n// Entire wrapper for `src/cli.ts` usage of this function\nexport async function handleCLiDumpParseTree(args: CommanderSubcommand.info.schemaType): Promise<0 | 1> {\n const useColors = !args.noColor; // Use colors unless --no-color flag is set\n const isStdin = isDumpFlagStdin(args.dumpParseTree);\n\n // Read stdin BEFORE startServer(), since startServer() hijacks stdin for the LSP connection\n let stdinContent = '';\n if (isStdin) {\n stdinContent = await readFromStdin();\n if (stdinContent.trim() === '') {\n logger.logToStderr('Error: No input provided. Please provide either a file path or pipe content to stdin.');\n return 1;\n }\n }\n\n startServer();\n await Analyzer.initialize();\n\n if (isStdin) {\n const doc = LspDocument.createTextDocumentItem('stdin.fish', stdinContent);\n return await cliDumpParseTree(doc, useColors);\n }\n\n // Original file-based logic\n const filePath = expandParseCliTreeFile(args.dumpParseTree as string);\n if (!SyncFileHelper.isFile(filePath)) {\n logger.logToStderr(`Error: Cannot read file at ${filePath}. Please check the file path and permissions.`);\n process.exit(1);\n }\n const doc = LspDocument.createFromPath(filePath);\n return await cliDumpParseTree(doc, useColors);\n}\n\n// ============================================================================\n// Semantic Tokens Dumping Functions\n// ============================================================================\n\n/**\n * Color scheme for semantic token types\n */\nconst tokenTypeColors = {\n function: chalk.blue.bold,\n variable: chalk.red,\n keyword: chalk.magenta.bold,\n decorator: chalk.yellow,\n string: chalk.green,\n operator: chalk.cyan,\n comment: chalk.gray,\n default: chalk.white,\n};\n\n/**\n * Get color function for a given token type\n */\nfunction getTokenTypeColor(tokenType: string, useColors: boolean): (text: string) => string {\n if (!useColors) return (text: string) => text;\n return tokenTypeColors[tokenType as keyof typeof tokenTypeColors] || tokenTypeColors.default;\n}\n\n/**\n * Decode modifiers from bitmask\n */\nfunction decodeModifiers(modifiersMask: number): string[] {\n const modifiers: string[] = [];\n const legend = FishSemanticTokens.legend.tokenModifiers;\n\n for (let i = 0; i < legend.length; i++) {\n if (modifiersMask & 1 << i) {\n modifiers.push(legend[i]!);\n }\n }\n\n return modifiers;\n}\n\n/**\n * Formats semantic tokens into a human-readable string representation.\n * Shows each token with its position, length, type, and modifiers.\n */\nfunction formatSemanticTokens(data: number[], source: string, useColors: boolean): string {\n if (data.length === 0) {\n return useColors ? chalk.gray('(no semantic tokens)') : '(no semantic tokens)';\n }\n\n const lines = source.split('\\n');\n const legend = FishSemanticTokens.legend;\n const results: string[] = [];\n\n // Semantic tokens are encoded as a flat array of integers\n // [deltaLine, deltaStart, length, tokenType, modifiers, ...]\n let currentLine = 0;\n let currentChar = 0;\n\n for (let i = 0; i < data.length; i += 5) {\n const deltaLine = data[i]!;\n const deltaStart = data[i + 1]!;\n const length = data[i + 2]!;\n const tokenTypeIndex = data[i + 3]!;\n const modifiersMask = data[i + 4]!;\n\n // Update position\n currentLine += deltaLine;\n if (deltaLine > 0) {\n currentChar = deltaStart;\n } else {\n currentChar += deltaStart;\n }\n\n // Get token information\n const tokenType = legend.tokenTypes[tokenTypeIndex] || 'unknown';\n const modifiers = decodeModifiers(modifiersMask);\n\n // Extract the actual text from the source\n const line = lines[currentLine] || '';\n const tokenText = line.substring(currentChar, currentChar + length);\n\n // Format the output\n const posStr = `${currentLine}:${currentChar}`;\n const typeColor = getTokenTypeColor(tokenType, useColors);\n const dimColor = useColors ? chalk.dim : (text: string) => text;\n const boldColor = useColors ? chalk.bold : (text: string) => text;\n\n let tokenInfo = `${dimColor(posStr.padEnd(10))} `;\n tokenInfo += `${typeColor(tokenType.padEnd(12))} `;\n tokenInfo += `${dimColor('len=')}${length.toString().padEnd(3)} `;\n\n if (modifiers.length > 0) {\n const modStr = `[${modifiers.join(', ')}]`;\n tokenInfo += `${dimColor(modStr.padEnd(30))} `;\n } else {\n tokenInfo += `${dimColor(''.padEnd(30))} `;\n }\n\n tokenInfo += `${boldColor('\"')}${tokenText}${boldColor('\"')}`;\n\n results.push(tokenInfo);\n }\n\n return results.join('\\n');\n}\n\n/**\n * Debug utility that shows semantic tokens for a source file.\n * Displays the source code and the semantic tokens.\n *\n * @param document - The LspDocument to debug\n * @param useColors - Whether to use color output\n * @returns Object containing both source and semantic tokens as strings\n */\nexport function debugSemanticTokens(document: LspDocument, useColors: boolean = true): SemanticTokensOutput {\n const source = document.getText();\n\n // Get semantic tokens for the document using the simplified handler\n const semanticTokens = semanticTokenHandler({\n textDocument: { uri: document.uri },\n });\n\n // Format the semantic tokens into a readable string\n const tokens = formatSemanticTokens(semanticTokens.data, source, useColors);\n\n return {\n source,\n tokens,\n };\n}\n\n/**\n * CLI handler for dumping semantic tokens\n */\nexport async function cliDumpSemanticTokens(document: LspDocument, useColors: boolean = true): Promise<0 | 1> {\n await Analyzer.initialize();\n\n // Analyze the document to ensure the analyzer cache is populated\n analyzer.analyze(document);\n\n const { tokens } = debugSemanticTokens(document, useColors);\n\n // Output the semantic tokens to stdout\n logger.logToStdout(tokens);\n if (tokens.trim().length === 0 || tokens.includes('(no semantic tokens)')) {\n const errorMsg = useColors ? chalk.red('No semantic tokens available for this document.') : 'No semantic tokens available for this document.';\n logger.logToStderr(errorMsg);\n return 1;\n }\n return 0;\n}\n\n// ============================================================================\n// Symbol Tree Dumping Functions\n// ============================================================================\n\n/**\n * Color scheme for FishSymbolKind values\n */\nconst symbolKindColors: Record string> = {\n FUNCTION: chalk.blue.bold,\n ALIAS: chalk.blue,\n SET: chalk.red,\n EXPORT: chalk.red.bold,\n READ: chalk.green,\n FOR: chalk.cyan,\n VARIABLE: chalk.red,\n FUNCTION_VARIABLE: chalk.magenta,\n ARGPARSE: chalk.yellow,\n COMPLETE: chalk.cyan.bold,\n EVENT: chalk.magenta.bold,\n FUNCTION_EVENT: chalk.magenta,\n INLINE_VARIABLE: chalk.red,\n};\n\n/**\n * Short tag prefix for each symbol kind category\n */\nconst symbolIconTag: Record = {\n FUNCTION: '',\n ALIAS: '',\n COMPLETE: '',\n SET: '',\n READ: '',\n FOR: '',\n VARIABLE: '',\n FUNCTION_VARIABLE: '',\n EXPORT: '',\n INLINE_VARIABLE: '',\n ARGPARSE: '',\n EVENT: '',\n FUNCTION_EVENT: '',\n};\n\nconst symbolTextTag: Record = {\n FUNCTION: 'f',\n ALIAS: 'f',\n COMPLETE: 'f',\n SET: 'v',\n READ: 'v',\n FOR: 'v',\n VARIABLE: 'v',\n FUNCTION_VARIABLE: 'v',\n EXPORT: 'v',\n INLINE_VARIABLE: 'v',\n ARGPARSE: 'v',\n EVENT: 'e',\n FUNCTION_EVENT: 'e',\n};\n\nconst treeColor = chalk.gray.bold;\n\nconst tagColors: Record string> = {\n f: chalk.blue,\n v: chalk.magenta,\n e: chalk.yellow,\n};\n\nfunction formatSymbolLine(symbol: FishSymbol, useIcons: boolean): string {\n const scopeTag = symbol.scope?.scopeTag || 'unknown';\n const kindColor = symbolKindColors[symbol.fishKind] || chalk.white;\n const textTag = symbolTextTag[symbol.fishKind] || '?';\n const tag = useIcons ? symbolIconTag[symbol.fishKind] || textTag : textTag;\n const tagColor = tagColors[textTag] || chalk.white;\n const tagStr = tagColor(tag);\n const nameStr = chalk.bold(symbol.name);\n const { start } = symbol.toLocation().range;\n const posStr = chalk.dim(`[${start.line}, ${start.character}]`);\n const scopeStr = chalk.dim(`(${scopeTag})`);\n const kindStr = kindColor(`(${symbol.fishKind})`);\n return `${tagStr} ${nameStr} ${posStr} ${scopeStr} ${kindStr}`;\n}\n\nfunction formatColoredSymbolNodes(symbols: FishSymbol[], prefix: string, useIcons: boolean): string {\n let result = '';\n\n for (let i = 0; i < symbols.length; i++) {\n const symbol = symbols[i]!;\n const isLast = i === symbols.length - 1;\n const connector = treeColor(isLast ? '└── ' : '├── ');\n const childPrefix = treeColor(isLast ? ' ' : '│ ');\n\n result += `${prefix}${connector}${formatSymbolLine(symbol, useIcons)}\\n`;\n\n if (symbol.children && symbol.children.length > 0) {\n result += formatColoredSymbolNodes(symbol.children, prefix + childPrefix, useIcons);\n }\n }\n\n return result;\n}\n\n/**\n * Formats the symbol tree with color highlighting and tree-style connectors\n */\nfunction formatColoredSymbolTree(symbols: FishSymbol[], rootLabel: string, useIcons: boolean): string {\n return chalk.black.dim(rootLabel) + '\\n' + formatColoredSymbolNodes(symbols, '', useIcons);\n}\n\n/**\n * CLI handler for dumping the symbol tree\n */\nexport async function cliDumpSymbolTree(document: LspDocument, useColors: boolean = true, useIcons: boolean = true): Promise<0 | 1> {\n await Analyzer.initialize();\n\n // Parse and analyze the document\n const tree = analyzer.parser.parse(document.getText());\n const rootNode = tree.rootNode;\n\n // Build the FishSymbol tree\n const symbols = processNestedTree(document, ...rootNode.children);\n\n // Determine root label from document URI\n // const uriPath = document.uri.replace(/^file:\\/\\//, '');\n let rootLabel = document.uri.includes('stdin')\n ? `/proc/${process.pid}/fd/0`\n : document.getFilePath();\n\n rootLabel = rootLabel.replace(os.homedir(), '~');\n\n // Format the symbol tree\n const output = useColors\n ? formatColoredSymbolTree(symbols, rootLabel, useIcons)\n : rootLabel + '\\n' + formatFishSymbolTree(symbols);\n\n if (output.trim().length === 0) {\n const errorMsg = useColors ? chalk.red('No symbols found in this document.') : 'No symbols found in this document.';\n logger.logToStderr(errorMsg);\n return 1;\n }\n\n logger.logToStdout(output);\n return 0;\n}\n\n/**\n * Main wrapper for `src/cli.ts` usage of symbol tree dumping\n */\nexport async function handleCLiDumpSymbolTree(args: CommanderSubcommand.info.schemaType): Promise<0 | 1> {\n const useColors = !args.noColor;\n const useIcons = args.icons !== false;\n const isStdin = isDumpFlagStdin(args.dumpSymbolTree);\n\n // Read stdin BEFORE startServer(), since startServer() hijacks stdin for the LSP connection\n let stdinContent = '';\n if (isStdin) {\n stdinContent = await readFromStdin();\n if (stdinContent.trim() === '') {\n logger.logToStderr('Error: No input provided. Please provide either a file path or pipe content to stdin.');\n return 1;\n }\n }\n\n startServer();\n await Analyzer.initialize();\n\n if (isStdin) {\n const doc = LspDocument.createTextDocumentItem('stdin.fish', stdinContent);\n return await cliDumpSymbolTree(doc, useColors, useIcons);\n }\n\n // File-based logic\n const filePath = expandParseCliTreeFile(args.dumpSymbolTree as string);\n if (!SyncFileHelper.isFile(filePath)) {\n logger.logToStderr(`Error: Cannot read file at ${filePath}. Please check the file path and permissions.`);\n process.exit(1);\n }\n const doc = LspDocument.createFromPath(filePath);\n return await cliDumpSymbolTree(doc, useColors, useIcons);\n}\n\n/**\n * Main wrapper for `src/cli.ts` usage of semantic tokens dumping\n */\nexport async function handleCLiDumpSemanticTokens(args: CommanderSubcommand.info.schemaType): Promise<0 | 1> {\n const useColors = !args.noColor; // Use colors unless --no-color flag is set\n const isStdin = isDumpFlagStdin(args.dumpSemanticTokens);\n\n // Read stdin BEFORE startServer(), since startServer() hijacks stdin for the LSP connection\n let stdinContent = '';\n if (isStdin) {\n stdinContent = await readFromStdin();\n if (stdinContent.trim() === '') {\n logger.logToStderr('Error: No input provided. Please provide either a file path or pipe content to stdin.');\n return 1;\n }\n }\n\n startServer();\n\n if (isStdin) {\n const doc = LspDocument.createTextDocumentItem('stdin.fish', stdinContent);\n return await cliDumpSemanticTokens(doc, useColors);\n }\n\n // Original file-based logic\n const filePath = expandParseCliTreeFile(args.dumpSemanticTokens as string);\n if (!SyncFileHelper.isFile(filePath)) {\n logger.logToStderr(`Error: Cannot read file at ${filePath}. Please check the file path and permissions.`);\n process.exit(1);\n }\n const doc = LspDocument.createFromPath(filePath);\n return await cliDumpSemanticTokens(doc, useColors);\n}\n"
},
{
"path": "src/utils/commander-cli-subcommands.ts",
"content": "import chalk from 'chalk';\nimport fs, { readFileSync, existsSync } from 'fs';\nimport { homedir } from 'os';\nimport path, { resolve } from 'path';\nimport { z } from 'zod';\nimport PackageJSON from '../../package.json';\nimport { commandBin } from '../cli';\nimport { config } from '../config';\nimport { logger } from '../logger';\nimport { SyncFileHelper } from './file-operations';\nimport { getCurrentExecutablePath, getFishBuildTimeFilePath, getManFilePath, getProjectRootPath, isBundledEnvironment } from './path-resolution';\nimport { maxWidthForOutput } from './startup';\nimport { vfs } from '../virtual-fs';\nimport FishServer from '../server';\n\n/**\n * Accumulate the arguments into two arrays, '--enable' and '--disable'\n * More than one enable/disable flag can be used, but the output will be\n * the stored across two resulting arrays (if both flags have values as input).\n * Handles some of the default commands, such as '--help', and '-s, --show'\n * from the command line args.\n */\nexport function accumulateStartupOptions(args: string[]): {\n enabled: string[];\n disabled: string[];\n dumpCmd: boolean;\n} {\n const [_subcmd, ...options] = args;\n const filteredOptions = filterStartCommandArgs(options);\n const [enabled, disabled]: [string[], string[]] = [[], []];\n let dumpCmd = false;\n let current: string[];\n filteredOptions?.forEach(arg => {\n if (['--enable', '--disable'].includes(arg)) {\n if (arg === '--enable') {\n current = enabled;\n }\n if (arg === '--disable') {\n current = disabled;\n }\n return;\n }\n if (['-h', '--help', 'help'].includes(arg)) {\n // commandBin.commands.find(command => command.name() === subcmd)!.outputHelp();\n // process.exit(0);\n return;\n }\n if (['--dump'].includes(arg)) {\n logger.logToStdout('SEEN SHOW COMMAND! dumping...');\n dumpCmd = true;\n return;\n }\n if (arg.startsWith('-')) {\n return;\n }\n if (current) {\n current?.push(arg);\n }\n });\n return { enabled, disabled, dumpCmd };\n}\n\nexport namespace SubcommandEnv {\n\n export type ArgsType = {\n create?: boolean;\n show?: boolean;\n showDefault?: boolean;\n only?: string[] | string | undefined;\n comments?: boolean;\n global?: boolean;\n local?: boolean;\n export?: boolean;\n confd?: boolean;\n names?: boolean;\n joined?: boolean;\n json?: boolean;\n };\n\n export type HandlerOptionsType = {\n only: string[] | undefined;\n comments: boolean;\n global: boolean;\n local: boolean;\n export: boolean;\n confd: boolean;\n json: boolean;\n };\n\n export const defaultHandlerOptions: HandlerOptionsType = {\n only: undefined,\n comments: true,\n global: true,\n local: false,\n export: true,\n confd: false,\n json: false,\n };\n\n /**\n * Get the output type based on the cli env args\n * Only one of these options is allowed at a time:\n * -c, --create `create the default env file`\n * --show-default: `same as --create`\n * -s, --show: `show the current values in use`\n * If `fish-lsp env` is called without any of the flags above, it will default to `create`\n */\n export function getOutputType(args: ArgsType): 'show' | 'create' | 'showDefault' {\n return args.showDefault ? 'showDefault' : args.show ? 'show' : 'create';\n }\n\n export function getOnly(args: ArgsType): string[] | undefined {\n if (args.only) {\n const only = Array.isArray(args.only) ? args.only : [args.only];\n return only.reduce((acc: string[], value) => {\n acc.push(...value.split(',').map(v => v.trim()));\n return acc;\n }, []);\n }\n return undefined;\n }\n\n export function toEnvOutputOptions(args: ArgsType): HandlerOptionsType {\n const only = getOnly(args);\n return {\n only,\n comments: args.comments ?? true,\n global: args.global ?? true,\n local: args.local ?? false,\n export: args.export ?? true,\n confd: args.confd ?? false,\n json: args.json ?? false,\n };\n }\n}\n\nexport function getEnvOnlyArgs(cliEnvOnly: string | string[] | undefined): string[] | undefined {\n const splitOnlyValues = (v: string) => v.split(',').map(value => value.trim());\n const isValidOnlyInput = (v: unknown): v is string | string[] =>\n typeof v === 'string'\n || Array.isArray(v) && v.every((value) => typeof value === 'string');\n const onlyArrayBuilder = (v: string | string[]) => {\n if (typeof v === 'string') {\n return splitOnlyValues(v);\n }\n return v.reduce((acc: string[], value) => {\n acc.push(...splitOnlyValues(value));\n return acc;\n }, []);\n };\n if (!cliEnvOnly || !isValidOnlyInput(cliEnvOnly)) return undefined;\n const only = Array.from(cliEnvOnly);\n return onlyArrayBuilder(only);\n}\n\n// filter out the start command args that are not used for the --enable/--disable values\nfunction filterStartCommandArgs(args: string[]): string[] {\n const filteredArgs = [];\n let skipNext = false;\n for (const arg of args) {\n // Skip this argument if the previous iteration marked it for skipping\n if (skipNext) {\n skipNext = false;\n continue;\n }\n\n // Check if the current arg is one of the flags that take values\n if (arg === '--socket' || arg === '--max-files' || arg === '--memory-limit') {\n skipNext = true; // Skip both the flag and its value\n continue;\n }\n\n // Check if the current arg is one of the flags without values\n if (arg === '--stdio' || arg === '--node-ipc') {\n continue;\n }\n\n // For flags with values in the format --flag=value\n if (arg.startsWith('--socket=') || arg.startsWith('--max-files=') || arg.startsWith('--memory-limit=')) {\n continue;\n }\n\n // Otherwise, keep the argument\n filteredArgs.push(arg);\n }\n\n return filteredArgs;\n}\n\n/// HELPERS\nexport const smallFishLogo = () => '><(((°> FISH LSP';\nexport const RepoUrl = PackageJSON.repository?.url.slice(0, -4);\nexport const PackageVersion = PackageJSON.version;\n\nexport const PathObj: { [K in 'bin' | 'root' | 'path' | 'manFile' | 'execFile']: string } = {\n ['bin']: getCurrentExecutablePath(),\n ['root']: getProjectRootPath(),\n ['path']: getProjectRootPath(),\n ['execFile']: getCurrentExecutablePath(),\n ['manFile']: getManFilePath(),\n};\n\nexport type VersionTuple = {\n major: number;\n minor: number;\n patch: number;\n raw: string;\n};\n\nexport namespace DepVersion {\n\n /**\n * Extracts the major, minor, and patch version numbers from a version string.\n */\n export function minimumNodeVersion(): VersionTuple {\n const versionString = PackageJSON.engines.node?.toString();\n const version = extract(versionString);\n if (!version) {\n return extract('>=20.0.0')!; // Fallback to a default version if extraction fails\n }\n return version;\n }\n\n export function extract(versionString: string): VersionTuple | null {\n // Match major.minor.patch, ignoring operators and prerelease/build metadata\n const match = versionString.match(/^[^\\d]*(\\d+)\\.(\\d+)\\.(\\d+)/);\n\n if (!match) return null;\n\n const [, majorStr, minorStr, patchStr] = match;\n\n return {\n major: parseInt(majorStr!, 10),\n minor: parseInt(minorStr!, 10),\n patch: parseInt(patchStr!, 10),\n raw: `${majorStr}.${minorStr}.${patchStr}`,\n };\n }\n\n export function compareVersions(a: VersionTuple, b: VersionTuple): number {\n if (a.major !== b.major) return a.major - b.major;\n if (a.minor !== b.minor) return a.minor - b.minor;\n return a.patch - b.patch;\n }\n\n /**\n * Compares two version tuples and returns true if the current version satisfies the required version.\n * @param current - The current version tuple.\n * @param required - The required version tuple.\n * @returns true if current version is greater than or equal to required version, false otherwise.\n */\n export function satisfies(current: VersionTuple, required: VersionTuple): boolean {\n return compareVersions(current, required) >= 0;\n }\n}\n\nexport const PackageLspVersion = PackageJSON.dependencies['vscode-languageserver-protocol']!.toString();\n\nexport const PackageNodeRequiredVersion = DepVersion.minimumNodeVersion();\n\n/**\n * shows last compile bundle time in server cli executable\n */\nconst getOutTime = () => {\n // First check if build time is embedded via environment variable (for bundled version)\n if (process.env.FISH_LSP_BUILD_TIME) {\n try {\n const buildTimeData = JSON.parse(process.env.FISH_LSP_BUILD_TIME);\n return buildTimeData.timestamp || new Date(buildTimeData.isoTimestamp).toLocaleString(undefined, { dateStyle: 'short', timeStyle: 'medium' });\n } catch (e) {\n // If parsing fails, return as-is (fallback for old format)\n return process.env.FISH_LSP_BUILD_TIME;\n }\n }\n\n // Fallback to reading from file (for development version)\n const buildFile = getFishBuildTimeFilePath();\n try {\n const fileContent = readFileSync(buildFile, 'utf8');\n const buildTimeData = JSON.parse(fileContent);\n return buildTimeData.timestamp || buildTimeData.isoTimestamp;\n } catch (e) {\n logger.logToStderr(`Error reading build-time file: ${buildFile}`);\n logger.error([\n `Error reading build-time file: ${buildFile}`,\n `Could not read build time from file: ${e}`,\n ]);\n return 'unknown';\n }\n};\n\nexport type BuildTimeJsonObj = {\n date: string | Date;\n timestamp: string;\n isoTimestamp: string;\n unix: number;\n version: string;\n nodeVersion: string;\n reproducible?: boolean;\n [key: string]: any;\n};\nexport const getBuildTimeJsonObj = (): BuildTimeJsonObj | undefined => {\n // First check if build time is embedded via environment variable (for bundled version)\n if (process.env.FISH_LSP_BUILD_TIME) {\n try {\n const jsonObj: BuildTimeJsonObj = JSON.parse(process.env.FISH_LSP_BUILD_TIME);\n return { ...jsonObj, date: new Date(jsonObj.date) };\n } catch (e) {\n logger.logToStderr(`Error parsing embedded build-time JSON: ${e}`);\n }\n }\n\n // Fallback to reading from file (for development version)\n try {\n const jsonFile = getFishBuildTimeFilePath();\n const jsonContent = readFileSync(jsonFile, 'utf8');\n const jsonObj: BuildTimeJsonObj = JSON.parse(jsonContent);\n return { ...jsonObj, date: new Date(jsonObj.date) };\n } catch (e) {\n logger.logToStderr(`Error reading build-time JSON file: ${e}`);\n logger.error(`Error reading build-time JSON file: ${e}`);\n }\n return undefined;\n};\n\nexport const isPkgBinary = () => {\n return typeof __dirname !== 'undefined' ? resolve(__dirname).startsWith('/snapshot/') : false;\n};\n\n/**\n * Detect if the binary is installed globally by checking if it's accessible via PATH\n */\nexport const isInstalledGlobally = (): boolean => {\n try {\n const execPath = getCurrentExecutablePath();\n\n // Check if the executable is in a global npm/yarn installation directory\n if (execPath.includes('/node_modules/.bin/') ||\n execPath.includes('/.npm/') ||\n execPath.includes('/.yarn/') ||\n execPath.includes('/usr/local/') ||\n execPath.includes('/opt/') ||\n execPath.includes('/.local/bin/')) {\n return true;\n }\n\n // Check if the current executable matches what would be found in PATH\n if (process.env.PATH) {\n const pathDirs = process.env.PATH.split(':');\n for (const dir of pathDirs) {\n const potentialPath = resolve(dir, 'fish-lsp');\n if (execPath === potentialPath || execPath.startsWith(potentialPath)) {\n return true;\n }\n }\n }\n\n return false;\n } catch {\n return false;\n }\n};\n\n/**\n * Detect the execution context: module, web, binary, or unknown\n * Also differentiates between direct execution and node execution\n */\nexport const getExecutionContext = (): 'module' | 'web' | 'binary' | 'node-binary' | 'node-module' | 'unknown' => {\n const execPath = getCurrentExecutablePath();\n const isNodeExecution = process.argv[0]?.includes('node');\n\n // Check if running in web context (no real filesystem paths)\n if (typeof (globalThis as any).window !== 'undefined' || typeof (globalThis as any).self !== 'undefined') {\n return 'web';\n }\n\n // Locations where the CLI Binary might be run from\n const cliPaths = ['/bin/fish-lsp', '/dist/fish-lsp', '/out/cli.js'];\n\n // Check if running as CLI binary\n if (cliPaths.some(path => execPath.endsWith(path))) {\n return isNodeExecution ? 'node-binary' : 'binary';\n }\n\n // Server/module execution paths\n const modulePaths = ['/out/server.js', '/dist/server.js', '/src/server.ts'];\n if (modulePaths.some(path => execPath.endsWith(path))) {\n return isNodeExecution ? 'node-module' : 'module';\n }\n\n // Default to unknown context\n return 'unknown';\n};\n\n/**\n * Generate build type string in format: (local|global) (bundled?) (module|web|binary)\n */\nexport const getBuildTypeString = (): string => {\n const result: string[] = [];\n\n // 1. Installation type: local or global\n const installType = isInstalledGlobally() ? 'global' : 'local';\n result.push(installType);\n\n // 2. Bundling status: bundled or not\n if (isPkgBinary()) {\n result.push('pkg-bundle'); // Special case for pkg bundling\n } else if (isBundledEnvironment() || getCurrentExecutablePath().includes('/dist/')) {\n result.push('bundled');\n }\n\n // 3. Execution context: module, web, or binary\n const context = getExecutionContext();\n result.push(context);\n\n return result.join(' ').trim();\n};\n\nexport const packageJsonVersion = () => {\n return PackageJSON.version || JSON.parse(fs.readFileSync(path.join(getProjectRootPath(), 'package.json'), 'utf8')).version;\n};\n\nexport const PkgJson = {\n ...PackageJSON,\n name: PackageJSON.name,\n version: PackageJSON.version,\n description: PackageJSON.description,\n npm: 'https://www.npmjs.com/fish-lsp',\n repository: PackageJSON.repository?.url.replace(/^git\\+/, '') || ' ',\n homepage: PackageJSON.homepage || ' ',\n lspVersion: PackageLspVersion,\n node: PackageNodeRequiredVersion,\n man: getManFilePath(),\n buildTime: getOutTime(),\n buildTimeObj: getBuildTimeJsonObj(),\n ...PathObj,\n};\n\nexport const SourcesDict: { [key: string]: string; } = {\n repo: 'https://github.com/ndonfris/fish-lsp',\n git: 'https://github.com/ndonfris/fish-lsp',\n npm: 'https://npmjs.com/fish-lsp',\n homepage: 'https://fish-lsp.dev',\n contributing: 'https://github.com/ndonfris/fish-lsp/blob/master/docs/CONTRIBUTING.md',\n issues: 'https://github.com/ndonfris/fish-lsp/issues?q=',\n report: 'https://github.com/ndonfris/fish-lsp/issues?q=',\n wiki: 'https://github.com/ndonfris/fish-lsp/wiki',\n discussions: 'https://github.com/ndonfris/fish-lsp/discussions',\n clientsRepo: 'https://github.com/ndonfris/fish-lsp-language-clients/',\n sourceMap: `https://github.com/ndonfris/fish-lsp/releases/download/v${PackageVersion}/sourcemaps.tar.gz`,\n sourcesList: [\n 'https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#headerPart',\n 'https://github.com/microsoft/vscode-extension-samples/tree/main',\n 'https://tree-sitter.github.io/tree-sitter/',\n 'https://github.com/ram02z/tree-sitter-fish',\n 'https://github.com/microsoft/vscode-languageserver-node/tree/main/testbed',\n 'https://github.com/Beaglefoot/awk-language-server/tree/master/server',\n 'https://github.com/bash-lsp/bash-language-server/tree/main/server/src',\n 'https://github.com/oncomouse/coc-fish',\n 'https://github.com/typescript-language-server/typescript-language-server#running-the-language-server',\n 'https://github.com/neoclide/coc-tsserver',\n 'https://www.npmjs.com/package/vscode-jsonrpc',\n 'https://github.com/Microsoft/vscode-languageserver-node',\n 'https://github.com/Microsoft/vscode-languageserver-node',\n 'https://github.com/microsoft/vscode-languageserver-node/blob/main/client/src/common',\n 'https://github.com/microsoft/vscode-languageserver-node/tree/main/server/src/common',\n ].join('\\n'),\n};\n\nexport function FishLspHelp() {\n const lspV = PackageJSON.dependencies['vscode-languageserver'].toString();\n return {\n\n beforeAll: `\n fish-lsp [-h | --help] [-v | --version] [--help-man] [--help-all] [--help-short]\n fish-lsp start [--enable | --disable] [--dump]\n fish-lsp info [--bare] [--repo] [--time] [--env]\n fish-lsp url [--repo] [--discussions] [--homepage] [--npm] [--contributions]\n [--wiki] [--issues] [--client-repo] [--sources]\n fish-lsp env [-c | --create] [-s | --show] [--no-comments]\n fish-lsp complete`,\n usage: `fish-lsp [OPTION]\n fish-lsp [COMMAND [OPTION...]]`,\n // fish-lsp [start | logger | info | url | complete] [options]\n // fish-lsp [-h | --help] [-v | --version] [--help-man] [--help-all] [--help-short]\n description: [\n ' A language server for the `fish-shell`, written in typescript. Currently supports',\n ` the following feature set from '${lspV || PackageLspVersion || '^9.0.1'}' of the language server protocol.`,\n ' More documentation is available for any command or subcommand via \\'-h/--help\\'.',\n '',\n ' The current language server protocol, reserves stdin/stdout for communication between the ',\n ' client and server. This means that when the server is started, it will listen for messages on',\n ' stdin/stdout. Command communication will be visible in `$fish_lsp_log_file`.',\n '',\n ` For more info, please visit: ${chalk.underline('https://github.com/ndonfris/fish-lsp')}`,\n ].join('\\n'),\n after: [\n '',\n 'Examples:',\n ' # Default setup, with all options enabled',\n ' > fish-lsp start',\n '',\n ' # Generate and store completions file:',\n ' > fish-lsp complete > ~/.config/fish/completions/fish-lsp.fish',\n ].join('\\n'),\n };\n}\n\nexport function FishLspManPage() {\n // Try to get man file from filesystem first (preferred - shows actual install location)\n const manFile = PathObj.manFile;\n if (manFile && existsSync(manFile)) {\n try {\n const content = readFileSync(manFile, 'utf8');\n return {\n path: manFile,\n content: content.split('\\n'),\n };\n } catch {\n // File exists but can't read it, fall through to VFS\n }\n }\n\n // Fallback to embedded man page from VFS\n if (vfs && vfs.allFiles && Array.isArray(vfs.allFiles)) {\n try {\n const virtual = vfs.allFiles.find(f => {\n return f.filepath.endsWith('man/fish-lsp.1') || f.filepath.endsWith('man/man1/fish-lsp.1');\n });\n\n if (virtual && virtual.content) {\n // Show warning that we're using embedded version\n if (process.stderr.isTTY) {\n process.stderr.write('\\x1b[33mWarning: Using embedded man page from virtual filesystem\\x1b[0m\\n');\n } else {\n process.stderr.write('Warning: Using embedded man page from virtual filesystem\\n');\n }\n\n return {\n path: `${virtual.filepath} (embedded)`,\n content: virtual.content.toString().split('\\n'),\n };\n }\n } catch (err) {\n // VFS access failed, continue to final error\n }\n }\n\n throw new Error('Man file not available');\n}\n\nexport function fishLspLogFile() {\n const logFile = SyncFileHelper.expandEnvVars(config.fish_lsp_log_file);\n if (!logFile) {\n logger.error('fish_lsp_log_file is not set in the config file.');\n return {\n path: '',\n content: [],\n };\n }\n const content = SyncFileHelper.read(logFile).split('\\n');\n return {\n path: resolve(logFile),\n content: content,\n };\n}\n\nexport namespace CommanderSubcommand {\n\n // Define the subcommands and their schemas\n export namespace start {\n export const schema = z.record(z.unknown()).and(\n z.object({\n enable: z.array(z.string()).optional().default([]),\n disable: z.array(z.string()).optional().default([]),\n dump: z.boolean().optional().default(false),\n port: z.string().optional(),\n socket: z.string().optional(),\n maxFiles: z.string().optional(),\n memoryLimit: z.string().optional(),\n stdio: z.boolean().optional().default(false),\n nodeIpc: z.boolean().optional().default(false),\n web: z.boolean().optional().default(false),\n }),\n );\n export type schemaType = z.infer;\n export function parse(args: unknown): schemaType {\n const isValidArgs = schema.safeParse(args);\n return isValidArgs?.success ? isValidArgs.data : schema.parse(args) || defaultSchema; // Validate the args against the schema\n }\n export const defaultSchema: schemaType = schema.parse({});\n }\n export namespace info {\n export const schema = z.record(z.unknown()).and(\n z.object({\n bin: z.boolean().optional().default(false),\n path: z.boolean().optional().default(false),\n buildTime: z.boolean().optional().default(false),\n buildType: z.boolean().optional().default(false),\n version: z.boolean().optional().default(false),\n lspVersion: z.boolean().optional().default(false),\n capabilities: z.boolean().optional().default(false),\n manFile: z.boolean().optional().default(false),\n logFile: z.boolean().optional().default(false),\n logsFile: z.boolean().optional().default(false),\n show: z.boolean().optional().default(false),\n verbose: z.boolean().optional().default(false),\n extra: z.boolean().optional().default(false),\n healthCheck: z.boolean().optional().default(false),\n checkHealth: z.boolean().optional().default(false),\n timeStartup: z.boolean().optional().default(false),\n timeOnly: z.boolean().optional().default(false),\n useWorkspace: z.string().optional().default(''),\n warning: z.boolean().optional().default(true),\n showFiles: z.boolean().optional().default(false),\n sourceMaps: z.boolean().optional().default(false),\n check: z.boolean().optional().default(false),\n status: z.boolean().optional().default(false),\n dumpParseTree: z.union([z.string(), z.boolean()]).optional().default(''),\n dumpSemanticTokens: z.union([z.string(), z.boolean()]).optional().default(''),\n dumpSymbolTree: z.union([z.string(), z.boolean()]).optional().default(''),\n icons: z.boolean().optional().default(true),\n color: z.boolean().optional().default(true),\n virtualFs: z.boolean().optional().default(false),\n }),\n );\n export type schemaType = z.infer;\n export function parse(args: unknown): schemaType {\n const isValidArgs = schema.safeParse(args);\n return isValidArgs?.success ? isValidArgs.data : schema.parse(args);\n }\n export const defaultSchema: schemaType = schema.parse({});\n export const skippable = z.object({\n healthCheck: z.boolean().default(false),\n checkHealth: z.boolean().default(false),\n timeStartup: z.boolean().default(false),\n timeOnly: z.boolean().default(false),\n useWorkspace: z.string().default(''),\n warning: z.boolean().default(true),\n icons: z.boolean().default(true),\n color: z.boolean().default(true),\n });\n export type skippableType = z.infer;\n export type skippableArgs = keyof skippableType;\n\n export const parseSkip = (args: unknown): z.infer => {\n const isValidArgs = skippable.safeParse(args);\n return isValidArgs?.success ? isValidArgs.data : skippable.parse(args) || skippable.parse({}); // Validate the args against the schema\n };\n\n export const allSkippableArgvs = [\n 'info',\n '--health-check',\n '--check-health',\n '--time-startup',\n '--time-only',\n '--use-workspace',\n '--no-warning',\n '--show-files',\n ] as const;\n\n export function handleBadArgs(args: schemaType) {\n const argsCount = countArgsWithValues('info', args);\n if (args.useWorkspace && args.useWorkspace.length > 0 && !args.timeStartup && !args.timeOnly && argsCount >= 1) {\n logger.logToStderr([\n buildErrorMessage('ERROR:', 'The option', '--use-workspace', 'should be used with either:', '--time-startup', 'or', '--time-only'),\n buildColoredCommandlineString({ subcommand: 'info', args: ['--time-startup', ...commandBin.args.slice(1)] }),\n buildErrorMessage(`If you believe this is a bug, please report it at ${chalk.underline.whiteBright(PkgJson.bugs.url)}`),\n ].join('\\n\\n'));\n process.exit(1);\n }\n const skippedArgs = commandBin.args.filter(arg => arg.startsWith('--') && allSkippableArgvs.some(skippable => arg.startsWith(skippable)));\n const unrelatedArgs = commandBin.args.filter(arg => arg.startsWith('--') && !allSkippableArgvs.some(skippable => arg.startsWith(skippable)));\n if (skippedArgs.length > 0 && unrelatedArgs.length > 0) {\n const unrelatedArgsSeen = argsToString(unrelatedArgs);\n logger.logToStderr([\n buildErrorMessage('ERROR:', 'Incompatible arguments provided.'),\n buildErrorMessage('FIXES:', 'Try removing the invalid arguments provided and running the command again.', 'INVALID ARGUMENTS:', ...unrelatedArgsSeen.replaceAll('\"', '').split(', ')),\n buildColoredCommandlineString({ subcommand: 'info', args: skippedArgs }),\n buildErrorMessage(`If you believe this is a bug, please report it at ${chalk.underline.whiteBright(PkgJson.bugs.url)}`),\n ].join('\\n\\n'));\n process.exit(1);\n }\n }\n\n export function handleFileArgs(args: schemaType) {\n const seenArgs = keys(args).filter(k => ['manFile', 'logFile', 'logsFile'].includes(k));\n const otherArgs = keys(args).filter(k => !['manFile', 'logFile', 'logsFile', 'show'].includes(k));\n const argsCount = otherArgs.length >= 1 ? otherArgs.length + 1 + seenArgs.length : otherArgs.length + seenArgs.length || 0;\n const hasLogFile = args.logFile || args.logsFile;\n const hasManFile = args.manFile;\n const hasShowFlag = args.show;\n if (hasLogFile) {\n const logObj = fishLspLogFile();\n const title = 'Log File';\n const message = args.show ? logObj.content.join('\\n') : logObj.path;\n log(argsCount, title, message);\n }\n if (hasManFile) {\n try {\n const manObj = FishLspManPage();\n const title = 'Man File';\n const message = args.show ? manObj.content.join('\\n') : manObj.path;\n if (manObj.content && manObj.path.startsWith('/man')) {\n logger.logToStderr('\\x1b[33mWarning: Displaying embedded\\x1b[0m');\n log(argsCount, title + ' (embedded)', manObj.content.join('\\n'));\n return;\n }\n log(argsCount, title, message);\n } catch (error) {\n log(argsCount, 'Man File', 'Error: Man file not available');\n }\n }\n if (!hasLogFile && !hasManFile && hasShowFlag) {\n logger.logToStderr([\n 'ERROR: flag `--show` requires either `--log-file` or `-man-file`',\n 'fish-lsp info [--log-file | --man-file] --show',\n ].join('\\n'));\n return 1;\n }\n return 0;\n }\n\n // Show output for the sourcemaps switch\n export function handleSourceMaps(args: schemaType) {\n let exitStatus = 0;\n if (!args.sourceMaps) return exitStatus;\n\n // check if all sourcemaps are present\n Object.values(SourceMaps).forEach(v => {\n if (!fs.existsSync(v) && !fs.readFileSync(getCurrentExecutablePath()).includes('//# sourceMappingURL=')) {\n exitStatus = 1;\n }\n });\n\n const showSourceMaps = () => {\n logger.logToStdout('-'.repeat(maxWidthForOutput())); // Add a blank line between maps\n const hasExternalSourceMaps = () => {\n for (const v of Object.values(SourceMaps)) {\n if (fs.existsSync(v)) return true;\n }\n return false;\n };\n if (!hasExternalSourceMaps() && fs.readFileSync(getCurrentExecutablePath()).includes('//# sourceMappingURL=')) {\n logger.logToStdoutJoined(chalk.white.bold('Inline Sourcemaps:'), ' ', chalk.blue(getCurrentExecutablePath().replace(homedir(), '~')));\n } else {\n for (const [k, v] of Object.entries(SourceMaps)) {\n const exists = fs.existsSync(v);\n logger.logToStdoutJoined(`${chalk.white('Sourcemap \\'')}`, chalk.blue(k), chalk.white(\"': \"), exists ? chalk.green('✅ Available') : chalk.red('❌ Not found'));\n if (exists) {\n logger.logToStdout(`${chalk.white('Path:')} ${chalk.blue(v.replace(homedir(), '~'))}`);\n } else {\n logger.logToStdout(`${chalk.white('Path:')} ${chalk.blue(v.replace(homedir(), '~'))} ${chalk.red('(not found)')}`);\n }\n }\n }\n logger.logToStdout('-'.repeat(maxWidthForOutput())); // Add a blank line between maps\n };\n\n if (args.all && !args.allPaths) {\n logger.logToStdout('-'.repeat(maxWidthForOutput()));\n sourcemaps().split('\\n').forEach(line => {\n if (line.includes(' (embedded inline)')) {\n logger.logToStdoutJoined(chalk.white('Sourcemaps are embedded in the binary at:'), ' ', chalk.blue(line.replace(' (embedded inline)', '').replace(homedir(), '~')));\n return 0;\n }\n const exists = fs.existsSync(line);\n logger.logToStdoutJoined(`${chalk.white('Sourcemap at path \\'')}`, chalk.blue(line.replace(homedir(), '~')), chalk.white(\"': \"), exists ? chalk.green('✅ Available') : chalk.red('❌ Not found'));\n });\n logger.logToStdout('-'.repeat(maxWidthForOutput())); // Add a blank line between maps\n return exitStatus;\n }\n\n if (args.allPaths) {\n sourcemaps().split('\\n').forEach(line => {\n if (line.includes(' (embedded inline)')) {\n logger.logToStdout(line.replace(' (embedded inline)', ''));\n } else {\n logger.logToStdout(line);\n }\n });\n return exitStatus;\n }\n\n if (args.check) {\n showSourceMaps();\n try {\n FishServer.throwError('Source map checking `fish-lsp info --source-maps --check`');\n } catch (error) {\n logger.logToStdoutJoined(chalk.dim('(Should throw error) '), chalk.red.underline.bold('Sourcemap check:'), ' ', chalk.red.dim((error as Error).message));\n FishServer.throwError('Source map checking passed `fish-lsp info --source-maps --check`');\n exitStatus = 1;\n }\n return exitStatus;\n }\n\n if (args.status) {\n sourcemaps().split('\\n').forEach(line => {\n if (line.includes(' (embedded inline)')) {\n logger.logToStdoutJoined(line.split(' ').at(0)!, ' ', chalk.blue('(embedded inline)'));\n } else {\n logger.logToStdoutJoined(line, ' ', fs.existsSync(line) ? chalk.green('(available)') : chalk.red('(not found)'));\n }\n });\n return exitStatus;\n }\n\n // Default source map path\n showSourceMaps();\n return exitStatus;\n }\n\n export function sourcemaps() {\n const result: string[] = [];\n if (fs.readFileSync(getCurrentExecutablePath()).includes('//# sourceMappingURL=')) {\n result.push(getCurrentExecutablePath() + ' (embedded inline)');\n } else {\n for (const v of Object.values(SourceMaps)) {\n if (fs.existsSync(v)) {\n result.push(v);\n }\n }\n }\n return result.join('\\n');\n }\n\n export function log(argsCount: number, title: string, message: string, alwaysShowTitle = false) {\n const isCapabilitiesString = title.toLowerCase() === 'capabilities';\n if (isCapabilitiesString) message = `\\n${message}`;\n if (argsCount > 1 || alwaysShowTitle || isCapabilitiesString) {\n logger.logToStdout(`${chalk.whiteBright.bold(`${title}:`)} ${chalk.cyan(message)}`);\n } else {\n logger.logToStdout(`${message}`);\n }\n }\n }\n export namespace url {\n export const schema = z.record(z.unknown()).and(\n z.object({\n repo: z.boolean().optional().default(false),\n discussions: z.boolean().optional().default(false),\n homepage: z.boolean().optional().default(false),\n npm: z.boolean().optional().default(false),\n contributions: z.boolean().optional().default(false),\n wiki: z.boolean().optional().default(false),\n issues: z.boolean().optional().default(false),\n clientRepo: z.boolean().optional().default(false),\n sources: z.boolean().optional().default(false),\n sourceMap: z.boolean().optional().default(false),\n }),\n );\n export type schemaType = z.infer;\n export function parse(args: unknown): schemaType {\n const isValidArgs = schema.safeParse(args);\n return isValidArgs?.success ? isValidArgs.data : schema.parse(args) || defaultSchema; // Validate the args against the schema\n }\n export const defaultSchema: schemaType = schema.parse({});\n }\n\n export namespace complete {\n export const schema = z.record(z.unknown()).and(\n z.object({\n names: z.boolean().optional().default(false),\n namesWithSummary: z.boolean().optional().default(false),\n fish: z.boolean().optional().default(false),\n toggles: z.boolean().optional().default(false),\n features: z.boolean().optional().default(false),\n envVariables: z.boolean().optional().default(false),\n envVariablesNames: z.boolean().optional().default(false),\n abbreviations: z.boolean().optional().default(false),\n }),\n );\n export type schemaType = z.infer;\n export function parse(args: unknown): schemaType {\n const isValidArgs = schema.safeParse(args);\n return isValidArgs?.success ? isValidArgs.data : schema.parse(args) || defaultSchema; // Validate the args against the schema\n }\n export const defaultSchema: schemaType = schema.parse({});\n }\n\n export namespace env {\n export const schema = z.record(z.unknown()).and(\n z.object({\n create: z.boolean().optional().default(false),\n show: z.boolean().optional().default(false),\n showDefault: z.boolean().optional().default(false),\n only: z.union([z.string(), z.array(z.string())]).optional(),\n comments: z.boolean().optional().default(true),\n global: z.boolean().optional().default(true),\n local: z.boolean().optional().default(false),\n export: z.boolean().optional().default(true),\n confd: z.boolean().optional().default(false),\n names: z.boolean().optional().default(false),\n joined: z.boolean().optional().default(false),\n }),\n );\n export type schemaType = z.infer;\n export function parse(args: unknown): schemaType {\n const isValidArgs = schema.safeParse(args);\n return isValidArgs?.success ? isValidArgs.data : schema.parse(args) || defaultSchema; // Validate the args against the schema\n }\n export const defaultSchema: schemaType = schema.parse({});\n }\n\n export const subcommands = [\n 'start',\n 'info',\n 'url',\n 'env',\n 'complete',\n ] as const;\n export type SubcommandType = (typeof subcommands)[number];\n\n export type schemas = typeof start.schema\n | typeof info.schema\n | typeof url.schema\n | typeof env.schema\n | typeof complete.schema;\n\n export const allSchemas = z.object({\n start: start.schema,\n info: info.schema,\n url: url.schema,\n env: env.schema,\n complete: complete.schema,\n });\n\n export function parseSubcommand(command: SubcommandType, args: unknown): z.infer {\n switch (command) {\n case 'start':\n return start.schema.parse(args);\n case 'info':\n return info.schema.parse(args);\n case 'url':\n return url.schema.parse(args);\n case 'env':\n return env.schema.parse(args);\n case 'complete':\n return complete.schema.parse(args);\n default:\n throw new Error(`Unknown subcommand: ${command}`);\n }\n }\n\n export const getSchemaKeys = (schema: typeof allSchemas) => {\n // return schema.keyof()?._def.values;\n return [...schema.keyof().options];\n };\n\n export function hasSkippable(command: SubcommandType) {\n switch (command) {\n case 'info':\n return true;\n // No skippable\n case 'start':\n case 'complete':\n case 'url':\n case 'env':\n return false;\n default:\n throw new Error(`Unknown subcommand: ${command}`);\n }\n }\n\n export function getSubcommand(command: SubcommandType): schemas {\n switch (command) {\n case 'start':\n return start.schema;\n case 'info':\n return info.schema;\n case 'url':\n return url.schema;\n case 'env':\n return env.schema;\n case 'complete':\n return complete.schema;\n default:\n throw new Error(`Unknown subcommand: ${command}`);\n }\n }\n\n export function countArgsWithValues(subcommand: SubcommandType, args: Record): number {\n const keysToCount = getSubcommand(subcommand).parse(args);\n const results: Record = {};\n const skippableArgs = hasSkippable(subcommand);\n const removed: Record = {};\n if (skippableArgs) {\n const skippable = info.skippable.parse(args);\n const defaults = info.skippable.parse({});\n for (const key in skippable) {\n if (key === subcommand) removed[key] = true;\n removed[key] = true;\n if (skippable[key as keyof typeof skippable] !== defaults[key as keyof typeof defaults]) {\n removed[key] = false;\n }\n }\n }\n for (const key in keysToCount) {\n if (key === subcommand) removed[key] = true;\n if (removed[key]) continue;\n if (keysToCount[key]) results[key] = true;\n }\n return Object.keys(results).length;\n }\n\n export function removeArgs(args: { [k: string]: unknown; }, ...keysToRemove: string[]) {\n const argKeys = keys(args);\n return argKeys.filter((key) => !keysToRemove.includes(key));\n }\n\n export const countArgs = (args: any): number => {\n return keys(args).length;\n };\n\n export const keys = (args: { [k: string]: unknown; }) => {\n return Object.entries(args)\n .filter(([key, value]) => !!key && !!value && !(key === 'warning' && value === true))\n .map(([key, _]) => key);\n };\n\n export function entries(args: any) {\n return Object.entries(args)\n .filter(([key, value]) => !!key && !!value && !(key === 'warning' && value === true))\n .map(([key, _]) => key);\n }\n\n export function noArgs(args: any): boolean {\n return Object.keys(args).length === 0;\n }\n\n export function argsToString(args: { [k: string]: unknown; } | string[]): string {\n if (Array.isArray(args)) {\n return args.map(m => ['', m, ''].join('\"')).join(', ');\n }\n return Object.keys(args).map(m => ['', m, ''].join('\"')).join(', ');\n }\n\n export function buildErrorMessage(...stdin: string[]) {\n return stdin.map((item, idx) => {\n const splitItem = item.split(' ');\n return splitItem.map((part) => {\n if (idx === 0 && part.toUpperCase() === part) {\n return chalk.bold.red(part);\n }\n if (part.startsWith('--')) {\n return chalk.whiteBright(part);\n }\n return chalk.redBright(part);\n }).join(' ');\n }).join(' ');\n }\n export type CommandlineOpts = {\n subcommand: 'start' | 'info' | 'url' | 'env' | 'complete' | '';\n args?: string[];\n prefixIndent?: boolean;\n showPrompt?: boolean;\n };\n\n // default values for commandline options\n const commandlineOpts = {\n subcommand: '',\n args: [],\n prefixIndent: true,\n showPrompt: true,\n } as CommandlineOpts;\n\n export function buildColoredCommandlineString(opts: CommandlineOpts): string {\n // set the default values if not provided\n if (opts.prefixIndent === undefined) opts.prefixIndent = commandlineOpts.prefixIndent;\n if (opts.showPrompt === undefined) opts.showPrompt = commandlineOpts.showPrompt;\n\n const result: string[] = [];\n\n // format the initial part of the command line\n if (opts.prefixIndent) result.push(' ');\n if (opts.showPrompt) {\n if (result.length > 0) {\n result[0] = result[0] + chalk.whiteBright('>_');\n } else {\n result.push(chalk.whiteBright('>_'));\n }\n }\n // add the command and subcommand\n result.push(chalk.magenta('fish-lsp'));\n result.push(chalk.blue(opts.subcommand));\n // add the args if provided\n if (opts.args && opts.args.length > 0) {\n opts.args.forEach((arg: string) => {\n const toAddArg = arg.replaceAll(/\"/g, '');\n if (toAddArg.includes('=')) {\n const [key, value] = toAddArg.split('=');\n result.push(`${chalk.white(key)}${chalk.bold.cyan('=')}${chalk.green(value)}`);\n } else {\n result.push(chalk.white(toAddArg));\n }\n });\n }\n // join the result with spaces\n return result.join(' ');\n }\n}\n\nexport function BuildCapabilityString() {\n const done = '✔️ '; // const done: string = '✅'\n const todo = '❌'; // const todo: string = '❌'\n const statusString = [\n `${done} complete`,\n `${done} hover`,\n `${done} rename`,\n `${done} definition`,\n `${done} references`,\n `${done} diagnostics`,\n `${done} signatureHelp`,\n `${done} codeAction`,\n `${todo} codeLens`,\n `${done} documentLink`,\n `${done} formatting`,\n `${done} rangeFormatting`,\n `${done} refactoring`,\n `${done} executeCommand`,\n `${done} workspaceSymbol`,\n `${done} documentSymbol`,\n `${done} foldingRange`,\n `${done} fold`,\n `${done} onType`,\n `${done} onDocumentSaveFormat`,\n `${done} onDocumentSave`,\n `${done} onDocumentOpen`,\n `${done} onDocumentChange`,\n `${todo} semanticTokens`,\n ].join('\\n');\n return statusString;\n}\n\n/**\n * Record of the sourcemaps for each file in the project.\n */\nexport const SourceMaps: Record = {\n 'dist/fish-lsp': path.resolve(path.dirname(getCurrentExecutablePath()), '..', 'dist', 'fish-lsp.map'),\n};\n"
},
{
"path": "src/utils/completion/comment-completions.ts",
"content": "import { Command, Position, Range, TextEdit } from 'vscode-languageserver';\nimport { FishCommandCompletionItem, FishCompletionData } from './types';\nimport { StaticItems } from './static-items';\nimport { SyntaxNode } from 'web-tree-sitter';\nimport { DIAGNOSTIC_COMMENT_REGEX, DiagnosticAction, isValidErrorCode } from '../../diagnostics/comments-handler';\nimport { FishCompletionList } from './list';\nimport { SetupData } from './pager';\nimport { ErrorCodes } from '../../diagnostics/error-codes';\n\nexport function buildCommentCompletions(\n line: string,\n position: Position,\n node: SyntaxNode,\n data: SetupData,\n word: string,\n) {\n // FishCompletionItem.createData(data.uri, line, ,detail, documentation)\n const hashIndex = line.indexOf('#');\n\n // Create range from the # character to cursor\n const range = Range.create(\n Position.create(position.line, hashIndex),\n position,\n );\n\n // Command to retrigger completion\n const retriggerCommand: Command = {\n title: 'Suggest',\n command: 'editor.action.triggerSuggest',\n };\n\n const completions: FishCommandCompletionItem[] = [];\n\n if (position.line === 0) {\n completions.push(\n ...StaticItems.shebang.map(item => {\n item.textEdit = TextEdit.replace(range, item.label);\n return item;\n }),\n );\n }\n\n /**\n * add diagnostic comment strings:\n * `# @fish-lsp-disable`\n */\n const diagnosticComment = getCommentDiagnostics(line, position.line);\n if (!diagnosticComment) {\n completions.push(\n ...StaticItems.comment.map((item) => {\n item.textEdit = TextEdit.replace(range, `${item.label} `);\n item.command = retriggerCommand;\n return item;\n }));\n }\n\n /**\n * add diagnostic codes to the completion list\n * `# @fish-lsp-disable 1001`\n */\n if (diagnosticComment) {\n if (diagnosticComment?.codes) {\n const codeStrings = diagnosticComment?.codes.map(code => code.toString());\n completions.push(\n ...StaticItems.diagnostic\n .filter(item => !codeStrings.includes(item.label))\n .map((item) => {\n item.command = retriggerCommand;\n item.insertText = `${item.label} `;\n return item;\n }),\n );\n }\n }\n const completionData: FishCompletionData = {\n word,\n position,\n uri: data.uri,\n line,\n };\n\n return FishCompletionList.create(false, completionData, completions);\n}\n\nfunction getCommentDiagnostics(line: string, lineNumber: number) {\n const match = line.trim().match(DIAGNOSTIC_COMMENT_REGEX);\n if (!match) return null;\n\n const [, action, nextLine, codesStr] = match;\n\n const codeStrings = codesStr ? codesStr.trim().split(/\\s+/) : [];\n\n // Parse the diagnostic codes if present\n const parsedCodes = codeStrings\n .map(codeStr => parseInt(codeStr, 10))\n .filter(code => !isNaN(code));\n\n const validCodes: ErrorCodes.CodeTypes[] = [];\n const invalidCodes: string[] = [];\n\n codeStrings.forEach((codeStr, idx) => {\n const code = parsedCodes[idx];\n if (code && !isNaN(code) && isValidErrorCode(code)) {\n validCodes.push(code as ErrorCodes.CodeTypes);\n } else {\n invalidCodes.push(codeStr);\n }\n });\n\n return {\n action: action as DiagnosticAction,\n target: nextLine ? 'next-line' : 'line',\n codes: validCodes,\n lineNumber: lineNumber,\n invalidCodes: invalidCodes.length > 0 ? invalidCodes : undefined,\n };\n}\n"
},
{
"path": "src/utils/completion/documentation.ts",
"content": "import { MarkupContent } from 'vscode-languageserver';\nimport { FishCompletionItem, FishCompletionItemKind, CompletionExample } from './types';\nimport { execCmd, execCommandDocs } from '../exec';\nimport { md } from '../markdown-builder';\n\nexport async function getDocumentationResolver(item: FishCompletionItem): Promise {\n let docString: string = item.documentation.toString();\n if (!item.local) {\n switch (item.fishKind) {\n case FishCompletionItemKind.ABBR:\n docString = await getAbbrDocString(item.label) ?? docString;\n break;\n case FishCompletionItemKind.ALIAS:\n docString = await getAliasDocString(item.label, item.documentation.toString() || `alias ${item.label}`) ?? docString;\n break;\n case FishCompletionItemKind.COMBINER:\n case FishCompletionItemKind.STATEMENT:\n case FishCompletionItemKind.BUILTIN:\n docString = await getBuiltinDocString(item.label) ?? docString;\n break;\n case FishCompletionItemKind.COMMAND:\n docString = await getCommandDocString(item.label) ?? docString;\n break;\n case FishCompletionItemKind.FUNCTION:\n docString = await getFunctionDocString(item.label) ?? `(${md.bold('function')}) ${item.label}`;\n break;\n case FishCompletionItemKind.VARIABLE:\n docString = await getVariableDocString(item.label) ?? docString;\n break;\n case FishCompletionItemKind.EVENT:\n docString = await getEventHandlerDocString(item.documentation as string) ?? docString;\n break;\n case FishCompletionItemKind.COMMENT:\n case FishCompletionItemKind.SHEBANG:\n case FishCompletionItemKind.DIAGNOSTIC:\n docString = item.documentation.toString();\n break;\n case FishCompletionItemKind.STATUS:\n case FishCompletionItemKind.WILDCARD:\n case FishCompletionItemKind.REGEX:\n case FishCompletionItemKind.FORMAT_STR:\n case FishCompletionItemKind.ESC_CHARS:\n case FishCompletionItemKind.PIPE:\n docString ??= await getStaticDocString(item as FishCompletionItem);\n break;\n case FishCompletionItemKind.ARGUMENT:\n docString = await buildArgumentDocString(item);\n break;\n case FishCompletionItemKind.EMPTY:\n default:\n break;\n }\n }\n if (item.local) {\n return {\n kind: 'markdown',\n value: item.documentation.toString(),\n } as MarkupContent;\n }\n return {\n kind: 'markdown',\n value: docString,\n } as MarkupContent;\n}\n\n/**\n * builds FunctionDocumentation string\n */\nexport async function getFunctionDocString(name: string): Promise {\n function formatTitle(title: string[]) {\n const ensured = ensureMinLength(title, 5, '');\n const [path, autoloaded, line, scope, description] = ensured;\n\n return [\n `__\\`${path}\\`__`,\n `- autoloaded: ${autoloaded === 'autoloaded' ? '_true_' : '_false_'}`,\n `- line: _${line}_`,\n `- scope: _${scope}_`,\n `${description}`,\n ].map((str) => str.trim()).filter(l => l.trim().length).join('\\n');\n }\n const [title, body] = await Promise.all([\n execCmd(`functions -D -v ${name}`),\n execCmd(`functions --no-details ${name}`),\n ]);\n return [\n formatTitle(title),\n '___',\n '```fish',\n body.join('\\n'),\n '```',\n ].join('\\n') || '';\n}\n\nexport async function getStaticDocString(item: FishCompletionItem): Promise {\n let result = [\n '```text',\n `${item.label} - ${item.documentation}`,\n '```',\n ].join('\\n');\n item.examples?.forEach((example: CompletionExample) => {\n result += [\n '___',\n '```fish',\n `# ${example.title}`,\n example.shellText,\n '```',\n ].join('\\n');\n });\n return result;\n}\n\nasync function buildArgumentDocString(item: FishCompletionItem): Promise {\n if (!item.detail) {\n return md.codeBlock('fish', item.documentation.toString());\n }\n return [\n md.codeBlock('fish', item.documentation.toString()),\n md.separator(),\n item.detail,\n ].join('\\n');\n}\n\nexport async function getAbbrDocString(name: string): Promise {\n const items: string[] = await execCmd('abbr --show | string split \\' -- \\' -m1 -f2');\n function getAbbr(items: string[]): [ string, string ] {\n const start: string = `${name} `;\n for (const item of items) {\n if (item.startsWith(start)) {\n return [start.trimEnd(), item.slice(start.length)];\n }\n }\n return ['', ''];\n }\n const [title, body] = getAbbr(items);\n return [\n `Abbreviation: \\`${title}\\``,\n '___',\n '```fish',\n body.trimEnd(),\n '```',\n ].join('\\n') || '';\n}\n/**\n * builds MarkupString for builtin documentation\n */\nexport async function getBuiltinDocString(name: string): Promise {\n const cmdDocs: string = await execCommandDocs(name);\n if (!cmdDocs) {\n return undefined;\n }\n const splitDocs = cmdDocs.split('\\n');\n const startIndex = splitDocs.findIndex((line: string) => line.trim() === 'NAME');\n return [\n `__${name.toUpperCase()}__ - _https://fishshell.com/docs/current/cmds/${name.trim()}.html_`,\n '___',\n '```man',\n splitDocs.slice(startIndex).join('\\n'),\n '```',\n ].join('\\n');\n}\n\nexport async function getAliasDocString(label: string, line: string): Promise {\n return [\n `Alias: _${label}_`,\n '___',\n '```fish',\n line.split('\\t')[1],\n '```',\n ].join('\\n');\n}\n\n/**\n * builds MarkupString for event handler documentation\n */\nexport async function getEventHandlerDocString(documentation: string): Promise {\n const [label, ...commandArr] = documentation.split(/\\s/, 2);\n const command = commandArr.join(' ');\n const doc = await getFunctionDocString(command);\n if (!doc) {\n return [\n `Event: \\`${label}\\``,\n '___',\n `Event handler for \\`${command}\\``,\n ].join('\\n');\n }\n return [\n `Event: \\`${label}\\``,\n '___',\n doc,\n ].join('\\n');\n}\n\n/**\n * builds MarkupString for global variable documentation\n */\nexport async function getVariableDocString(name: string): Promise