tree shaking

bsconfig.schema.json

@@ -299,6 +299,66 @@
             "description": "Allow brighterscript features (classes, interfaces, etc...) to be included in BrightScript (`.brs`) files, and force those files to be transpiled.",
             "type": "boolean",
             "default": false
+        },
+        "treeShaking": {
+            "description": "Configuration for tree shaking (dead code elimination). Disabled by default; set `enabled: true` to opt in.",
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "enabled": {
+                    "description": "Enable tree shaking. Defaults to false.",
+                    "type": "boolean",
+                    "default": false
+                },
+                "keep": {
+                    "description": "List of keep rules. Functions matching any rule are always retained along with their full dependency closure. A plain string is shorthand for `{ functions: [string] }`.",
+                    "type": "array",
+                    "items": {
+                        "oneOf": [
+                            {
+                                "type": "string",
+                                "description": "Exact BrightScript function name to always keep."
+                            },
+                            {
+                                "type": "object",
+                                "additionalProperties": false,
+                                "minProperties": 1,
+                                "description": "Keep rule object. All specified fields must match (AND semantics). Rules are combined with OR semantics.",
+                                "properties": {
+                                    "src": {
+                                        "description": "Glob pattern(s) matched against the source file path.",
+                                        "oneOf": [
+                                            { "type": "string" },
+                                            { "type": "array", "items": { "type": "string" } }
+                                        ]
+                                    },
+                                    "dest": {
+                                        "description": "Glob pattern(s) matched against the package-relative destination path.",
+                                        "oneOf": [
+                                            { "type": "string" },
+                                            { "type": "array", "items": { "type": "string" } }
+                                        ]
+                                    },
+                                    "functions": {
+                                        "description": "Exact BrightScript function name(s) to keep.",
+                                        "oneOf": [
+                                            { "type": "string" },
+                                            { "type": "array", "items": { "type": "string" } }
+                                        ]
+                                    },
+                                    "matches": {
+                                        "description": "Glob/wildcard pattern(s) matched against the BrightScript function name.",
+                                        "oneOf": [
+                                            { "type": "string" },
+                                            { "type": "array", "items": { "type": "string" } }
+                                        ]
+                                    }
+                                }
+                            }
+                        ]
+                    }
+                }
+            }
         }
     }
 }

src/BsConfig.ts

@@ -213,6 +213,57 @@ export interface BsConfig {
      * scripts inside `source` that depend on bslib.brs.  Defaults to `source`.
      */
     bslibDestinationDir?: string;
+
+    /**
+     * Configuration for tree shaking (dead code elimination).
+     */
+    treeShaking?: TreeShakingConfig;
+}
+
+/**
+ * A single keep-rule entry in `treeShaking.keep`.
+ *
+ * A plain string is shorthand for `{ functions: [string] }`.
+ * An object entry must contain at least one of `src`, `dest`, `functions`, or `matches`.
+ * All fields present on one rule are combined with AND semantics.
+ * Rules across the list are combined with OR semantics.
+ */
+export type TreeShakingKeepEntry = string | TreeShakingKeepRule;
+
+export interface TreeShakingKeepRule {
+    /** Glob pattern(s) matched against the declaration's source file path. */
+    src?: string | string[];
+    /** Glob pattern(s) matched against the declaration's package-relative destination path. */
+    dest?: string | string[];
+    /** Exact function name(s) to keep (BrightScript/transpiled names). */
+    functions?: string | string[];
+    /** Glob/wildcard pattern(s) matched against the function name (BrightScript/transpiled names). */
+    matches?: string | string[];
+}
+
+export interface TreeShakingConfig {
+    /**
+     * Enable or disable tree shaking. Defaults to `false` (opt-in).
+     */
+    enabled?: boolean;
+    /**
+     * Declarations matching any rule in this list are always retained,
+     * along with their full dependency closure.
+     */
+    keep?: TreeShakingKeepEntry[];
+}
+
+/** Normalized internal form produced by `normalizeConfig`. */
+export interface NormalizedKeepRule {
+    src?: string[];
+    dest?: string[];
+    functions?: string[];
+    matches?: string[];
+}
+
+export interface NormalizedTreeShakingConfig {
+    enabled: boolean;
+    keep: NormalizedKeepRule[];
 }
 
 type OptionalBsConfigFields =
@@ -231,5 +282,6 @@ type OptionalBsConfigFields =
     | 'stagingDir';
 
 export type FinalizedBsConfig =
-    Omit<Required<BsConfig>, OptionalBsConfigFields>
-    & Pick<BsConfig, OptionalBsConfigFields>;
+    Omit<Required<BsConfig>, OptionalBsConfigFields | 'treeShaking'>
+    & Pick<BsConfig, OptionalBsConfigFields>
+    & { treeShaking: NormalizedTreeShakingConfig };

src/bscPlugin/BscPlugin.ts

@@ -1,6 +1,7 @@
 import { isBrsFile, isXmlFile } from '../astUtils/reflection';
+import type { AstEditor } from '../astUtils/AstEditor';
 import type { BeforeFileTranspileEvent, Plugin, OnFileValidateEvent, OnGetCodeActionsEvent, ProvideHoverEvent, OnGetSemanticTokensEvent, OnScopeValidateEvent, ProvideCompletionsEvent, ProvideDefinitionEvent, ProvideReferencesEvent, ProvideDocumentSymbolsEvent, ProvideWorkspaceSymbolsEvent } from '../interfaces';
-import type { Program } from '../Program';
+import type { Program, TranspileObj } from '../Program';
 import { CodeActionsProcessor } from './codeActions/CodeActionsProcessor';
 import { CompletionsProcessor } from './completions/CompletionsProcessor';
 import { DefinitionProvider } from './definition/DefinitionProvider';
@@ -14,6 +15,7 @@ import { ProgramValidator } from './validation/ProgramValidator';
 import { ScopeValidator } from './validation/ScopeValidator';
 import { XmlFileValidator } from './validation/XmlFileValidator';
 import { WorkspaceSymbolProcessor } from './symbols/WorkspaceSymbolProcessor';
+import { TreeShaker } from './treeShaker/TreeShaker';
 
 export class BscPlugin implements Plugin {
     public name = 'BscPlugin';
@@ -60,6 +62,18 @@ export class BscPlugin implements Plugin {
         }
     }
 
+    private treeShaker = new TreeShaker();
+
+    public beforeProgramTranspile(program: Program, entries: TranspileObj[], editor: AstEditor) {
+        if (!program.options.treeShaking.enabled) {
+            return;
+        }
+        this.treeShaker.analyze(program, program.options.treeShaking.keep);
+        for (const entry of entries) {
+            this.treeShaker.shake(entry.file, editor);
+        }
+    }
+
     private scopeValidator = new ScopeValidator();
 
     public onScopeValidate(event: OnScopeValidateEvent) {