feat: add shellcheckExternalSources config to make --external-sources optional

The --external-sources flag is currently hardcoded in every ShellCheck
invocation. On projects with many shell scripts that cross-source each
other (e.g. 100+ scripts with source-path=SCRIPTDIR in .shellcheckrc),
this causes exponential AST expansion — individual shellcheck processes
grow to 3-5 GB RSS and never terminate.

Adds a shellcheckExternalSources boolean config option (default: true
for backward compatibility) and SHELLCHECK_EXTERNAL_SOURCES env var.
When set to false, --external-sources is omitted from the ShellCheck
invocation, preventing the unbounded memory growth.

Fixes #874
Fixes #1375

Author: marcusquinn

server/src/config.ts

@@ -24,7 +24,12 @@ export const ConfigSchema = z.object({
   // If true, then all symbols from the workspace are included.
   includeAllWorkspaceSymbols: z.boolean().default(false),
 
-  // Additional ShellCheck arguments. Note that we already add the following arguments: --shell, --format, --external-sources."
+  // Controls whether ShellCheck is invoked with --external-sources. When enabled (default),
+  // ShellCheck follows source directives to lint referenced files. On projects with many
+  // cross-sourcing scripts this can cause unbounded memory growth. Set to false to disable.
+  shellcheckExternalSources: z.boolean().default(true),
+
+  // Additional ShellCheck arguments. Note that we already add the following arguments: --shell, --format, and --external-sources (if shellcheckExternalSources is true).
   shellcheckArguments: z
     .preprocess((arg) => {
       let argsList: string[] = []
@@ -87,6 +92,7 @@ export function getConfigFromEnvironmentVariables(): {
     includeAllWorkspaceSymbols: toBoolean(process.env.INCLUDE_ALL_WORKSPACE_SYMBOLS),
     logLevel: process.env[LOG_LEVEL_ENV_VAR],
     shellcheckArguments: process.env.SHELLCHECK_ARGUMENTS,
+    shellcheckExternalSources: toBoolean(process.env.SHELLCHECK_EXTERNAL_SOURCES),
     shellcheckPath: process.env.SHELLCHECK_PATH,
     shfmt: {
       path: process.env.SHFMT_PATH,

server/src/server.ts

@@ -277,7 +277,10 @@ export default class BashServer {
             logger.info('ShellCheck linting is disabled as "shellcheckPath" was not set')
             this.linter = undefined
           } else {
-            this.linter = new Linter({ executablePath: shellcheckPath })
+            this.linter = new Linter({
+              executablePath: shellcheckPath,
+              externalSources: this.config.shellcheckExternalSources,
+            })
           }
 
           const shfmtPath = this.config.shfmt?.path

server/src/shellcheck/index.ts

@@ -33,6 +33,7 @@ function safeFileURLToPath(uri: string): string | null {
 type LinterOptions = {
   executablePath: string
   cwd?: string
+  externalSources?: boolean
 }
 
 export type LintingResult = {
@@ -43,15 +44,17 @@ export type LintingResult = {
 export class Linter {
   private cwd: string
   public executablePath: string
+  private externalSources: boolean
   private uriToDebouncedExecuteLint: {
     [uri: string]: InstanceType<typeof Linter>['executeLint']
   }
   private _canLint: boolean
 
-  constructor({ cwd, executablePath }: LinterOptions) {
+  constructor({ cwd, executablePath, externalSources = true }: LinterOptions) {
     this._canLint = true
     this.cwd = cwd || process.cwd()
     this.executablePath = executablePath
+    this.externalSources = externalSources
     this.uriToDebouncedExecuteLint = Object.create(null)
   }
 
@@ -139,7 +142,7 @@ export class Linter {
 
     const args = [
       '--format=json1',
-      '--external-sources',
+      ...(this.externalSources ? ['--external-sources'] : []),
       ...sourcePathsArgs,
       ...additionalArgs,
     ]

vscode-client/package.json

@@ -73,10 +73,15 @@
           "default": "shellcheck",
           "description": "Controls the executable used for ShellCheck linting information. An empty string will disable linting."
         },
+        "bashIde.shellcheckExternalSources": {
+          "type": "boolean",
+          "default": true,
+          "description": "Controls whether ShellCheck is invoked with --external-sources. When enabled (default), ShellCheck follows source directives to lint referenced files. On projects with many cross-sourcing scripts this can cause unbounded memory growth. Set to false to disable."
+        },
         "bashIde.shellcheckArguments": {
           "type": "string",
           "default": "",
-          "description": "Additional ShellCheck arguments. Note that we already add the following arguments: --shell, --format, --external-sources."
+          "description": "Additional ShellCheck arguments. Note that we already add the following arguments: --shell, --format, and --external-sources (if shellcheckExternalSources is true)."
         },
         "bashIde.shfmt.path": {
           "type": "string",