From f5b045a8d828cc887775d18fde78c4cab3d3184f Mon Sep 17 00:00:00 2001
From: Tyler Smith <tyler@tksssoftware.com>
Date: Wed, 18 Mar 2026 09:27:21 -0300
Subject: [PATCH 01/44] Base tree shaking implementation

---
 src/bscPlugin/BscPlugin.ts                  |  13 +-
 src/bscPlugin/treeShaker/TreeShaker.spec.ts | 277 ++++++++++++++++++++
 src/bscPlugin/treeShaker/TreeShaker.ts      | 274 +++++++++++++++++++
 3 files changed, 563 insertions(+), 1 deletion(-)
 create mode 100644 src/bscPlugin/treeShaker/TreeShaker.spec.ts
 create mode 100644 src/bscPlugin/treeShaker/TreeShaker.ts

diff --git a/src/bscPlugin/BscPlugin.ts b/src/bscPlugin/BscPlugin.ts
index 5922a0599..17df319bb 100644
--- a/src/bscPlugin/BscPlugin.ts
+++ b/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,15 @@ export class BscPlugin implements Plugin {
         }
     }
 
+    private treeShaker = new TreeShaker();
+
+    public beforeProgramTranspile(program: Program, entries: TranspileObj[], editor: AstEditor) {
+        this.treeShaker.analyze(program);
+        for (const entry of entries) {
+            this.treeShaker.shake(entry.file, editor);
+        }
+    }
+
     private scopeValidator = new ScopeValidator();
 
     public onScopeValidate(event: OnScopeValidateEvent) {
diff --git a/src/bscPlugin/treeShaker/TreeShaker.spec.ts b/src/bscPlugin/treeShaker/TreeShaker.spec.ts
new file mode 100644
index 000000000..ad819e401
--- /dev/null
+++ b/src/bscPlugin/treeShaker/TreeShaker.spec.ts
@@ -0,0 +1,277 @@
+import { expect } from '../../chai-config.spec';
+import { Program } from '../../Program';
+import { standardizePath as s } from '../../util';
+import * as fsExtra from 'fs-extra';
+import undent from 'undent';
+
+describe.only('TreeShakerValidator', () => {
+    let program: Program;
+    const tempDir = s`${__dirname}/../.tmp`;
+    const rootDir = s`${tempDir}/rootDir`;
+    const stagingDir = s`${tempDir}/stagingDir`;
+
+    beforeEach(() => {
+        fsExtra.emptyDirSync(rootDir);
+        fsExtra.emptyDirSync(stagingDir);
+
+        program = new Program({ rootDir: rootDir, stagingDir: stagingDir });
+    });
+
+    afterEach(() => {
+        fsExtra.removeSync(tempDir);
+    });
+
+    async function getTranspiled(filePath: string) {
+        program.validate();
+        return (await program.getTranspiledFileContents(filePath)).code;
+    }
+
+    describe('tree shaking', () => {
+        it('removes unused functions from transpiled output', async () => {
+            program.setFile('source/main.bs', `
+                sub main()
+                    doSomething()
+                end sub
+
+                sub doSomething()
+                    print "used"
+                end sub
+
+                sub unusedFunction()
+                    print "never called"
+                end sub
+            `);
+
+            const code = await getTranspiled('source/main.bs');
+            expect(code).to.include('sub doSomething()');
+            expect(code).not.to.include('sub unusedFunction()');
+        });
+
+        it('preserves functions that are directly called', async () => {
+            program.setFile('source/main.bs', `
+                sub main()
+                    helper()
+                end sub
+
+                sub helper()
+                    print "I am called"
+                end sub
+            `);
+
+            const code = await getTranspiled('source/main.bs');
+            expect(code).to.include('sub helper()');
+        });
+
+        it('preserves Roku lifecycle entry points', async () => {
+            program.setFile('source/main.bs', `
+                sub main()
+                end sub
+
+                sub init()
+                end sub
+
+                sub onKeyEvent(key as string, press as boolean) as boolean
+                    return false
+                end sub
+
+                sub runUserInterface()
+                end sub
+
+                sub runTask()
+                end sub
+
+                sub onMessage()
+                end sub
+
+                sub removable()
+                end sub
+            `);
+
+            const code = await getTranspiled('source/main.bs');
+            expect(code).to.include('sub main()');
+            expect(code).to.include('sub init()');
+            expect(code).to.include('sub onKeyEvent(');
+            expect(code).to.include('sub runUserInterface()');
+            expect(code).to.include('sub runTask()');
+            expect(code).to.include('sub onMessage()');
+            expect(code).not.to.include('sub removable()');
+        });
+
+        it('preserves @keep annotated functions regardless of call sites', async () => {
+            program.setFile('source/main.bs', `
+                sub main()
+                end sub
+
+                @keep
+                sub mustStay()
+                    print "annotated with keep"
+                end sub
+
+                sub canGo()
+                    print "no annotation"
+                end sub
+            `);
+
+            const code = await getTranspiled('source/main.bs');
+            expect(code).to.include('sub mustStay()');
+            expect(code).not.to.include('sub canGo()');
+        });
+
+        it('preserves functions referenced as string literals (observeField pattern)', async () => {
+            program.setFile('source/main.bs', `
+                sub init()
+                    m.top.observeField("content", "onContentChanged")
+                end sub
+
+                sub onContentChanged()
+                    print "content changed"
+                end sub
+
+                sub unused()
+                end sub
+            `);
+
+            const code = await getTranspiled('source/main.bs');
+            expect(code).to.include('sub onContentChanged()');
+            expect(code).not.to.include('sub unused()');
+        });
+
+        it('preserves functions passed by reference as variables', async () => {
+            program.setFile('source/main.bs', `
+                sub init()
+                    m.top.observeField("content", onContentChanged)
+                end sub
+
+                sub onContentChanged()
+                    print "passed by reference"
+                end sub
+
+                sub unused()
+                end sub
+            `);
+
+            const code = await getTranspiled('source/main.bs');
+            expect(code).to.include('sub onContentChanged()');
+            expect(code).not.to.include('sub unused()');
+        });
+
+        it('preserves functions called via @. callfunc shorthand', async () => {
+            program.setFile('source/main.bs', `
+                sub init()
+                    m.someNode@.renderBlocks()
+                end sub
+
+                sub renderBlocks()
+                    print "callfunc target"
+                end sub
+
+                sub unused()
+                end sub
+            `);
+
+            const code = await getTranspiled('source/main.bs');
+            expect(code).to.include('sub renderBlocks()');
+            expect(code).not.to.include('sub unused()');
+        });
+
+        it('preserves namespaced functions that are called', async () => {
+            program.setFile('source/main.bs', `
+                namespace utils
+                    sub helper()
+                        print "namespaced helper"
+                    end sub
+
+                    sub unused()
+                        print "namespaced but never called"
+                    end sub
+                end namespace
+
+                sub main()
+                    utils.helper()
+                end sub
+            `);
+
+            const code = await getTranspiled('source/main.bs');
+            expect(code).to.include('utils_helper');
+            expect(code).not.to.include('utils_unused');
+        });
+
+        it('removes multiple unused functions in a single file', async () => {
+            program.setFile('source/main.bs', `
+                sub main()
+                end sub
+
+                sub unusedA()
+                end sub
+
+                sub unusedB()
+                end sub
+
+                sub unusedC()
+                end sub
+            `);
+
+            const code = await getTranspiled('source/main.bs');
+            expect(code).to.include('sub main()');
+            expect(code).not.to.include('sub unusedA()');
+            expect(code).not.to.include('sub unusedB()');
+            expect(code).not.to.include('sub unusedC()');
+        });
+    });
+
+    describe('XML interface functions', () => {
+        it('preserves functions declared in XML <interface><function> elements', async () => {
+            program.setFile('components/MyComponent.xml', undent`
+                <?xml version="1.0" encoding="utf-8" ?>
+                <component name="MyComponent" extends="Group">
+                    <interface>
+                        <function name="exposedToParent"/>
+                    </interface>
+                    <script type="text/brightscript" uri="MyComponent.bs"/>
+                </component>
+            `);
+            program.setFile('components/MyComponent.bs', `
+                sub init()
+                end sub
+
+                sub exposedToParent()
+                    print "called from parent via interface"
+                end sub
+
+                sub unused()
+                end sub
+            `);
+
+            const code = await getTranspiled('components/MyComponent.bs');
+            expect(code).to.include('sub exposedToParent()');
+            expect(code).not.to.include('sub unused()');
+        });
+
+        it('preserves functions referenced in XML field onChange attributes', async () => {
+            program.setFile('components/MyComponent.xml', undent`
+                <?xml version="1.0" encoding="utf-8" ?>
+                <component name="MyComponent" extends="Group">
+                    <interface>
+                        <field id="content" type="string" onChange="onContentChanged"/>
+                    </interface>
+                    <script type="text/brightscript" uri="MyComponent.bs"/>
+                </component>
+            `);
+            program.setFile('components/MyComponent.bs', `
+                sub init()
+                end sub
+
+                sub onContentChanged()
+                    print "field observer"
+                end sub
+
+                sub unused()
+                end sub
+            `);
+
+            const code = await getTranspiled('components/MyComponent.bs');
+            expect(code).to.include('sub onContentChanged()');
+            expect(code).not.to.include('sub unused()');
+        });
+    });
+});
diff --git a/src/bscPlugin/treeShaker/TreeShaker.ts b/src/bscPlugin/treeShaker/TreeShaker.ts
new file mode 100644
index 000000000..8c27e28bb
--- /dev/null
+++ b/src/bscPlugin/treeShaker/TreeShaker.ts
@@ -0,0 +1,274 @@
+import type { AstEditor } from '../../astUtils/AstEditor';
+import { isBrsFile, isDottedGetExpression, isLiteralString, isXmlFile } from '../../astUtils/reflection';
+import { WalkMode, createVisitor } from '../../astUtils/visitors';
+import type { BrsFile } from '../../files/BrsFile';
+import type { XmlFile } from '../../files/XmlFile';
+import type { BscFile } from '../../interfaces';
+import type { CallfuncExpression } from '../../parser/Expression';
+import { ParseMode } from '../../parser/Parser';
+import { EmptyStatement } from '../../parser/Statement';
+import type { FunctionStatement } from '../../parser/Statement';
+import type { Program } from '../../Program';
+import util from '../../util';
+
+export class TreeShaker {
+	/**
+	 * Roku lifecycle callbacks and framework entry points that must always be kept.
+	 * These are never removed regardless of whether they appear in call expressions.
+	 */
+	private static readonly ENTRY_POINTS = new Set([
+		'main',
+		'init',
+		'onkeyevent',
+		'onmessage',
+		'runuserinterface',
+		'runtask',
+	]);
+
+	// Fully-qualified lowercased function names → statement + file
+	private allFunctions = new Map<string, { statement: FunctionStatement; file: BrsFile }>();
+
+	// Names referenced in CallExpression nodes (both full namespaced and simple names)
+	private calledNames = new Set<string>();
+
+	// String literal values that look like identifiers (potential dynamic callFunc / observeField targets)
+	private stringRefs = new Set<string>();
+
+	// Functions declared in XML <interface><function name="..."/> elements
+	private xmlInterfaceFunctions = new Set<string>();
+
+	// Functions explicitly annotated with @keep — never removed regardless of references
+	private keepAnnotated = new Set<string>();
+
+	reset() {
+		this.allFunctions.clear();
+		this.calledNames.clear();
+		this.stringRefs.clear();
+		this.xmlInterfaceFunctions.clear();
+		this.keepAnnotated.clear();
+	}
+
+	/**
+	 * Two-pass analysis of the entire program:
+	 *
+	 * Pass 1 — collect every function definition so we have the complete set
+	 *           of names before any reference pass runs.
+	 *
+	 * Pass 2 — collect call sites, string literals (dynamic dispatch / observeField),
+	 *           and VariableExpression references.  The VariableExpression check is
+	 *           gated on the name matching a known function so that passing a function
+	 *           by reference (e.g. sgnode.observe(node, "field", onContentChanged))
+	 *           is detected even when the name never appears as a string literal or
+	 *           direct call.
+	 */
+	analyze(program: Program) {
+		this.reset();
+
+		// Pass 1 – definitions + XML interfaces
+		for (const file of Object.values(program.files)) {
+			if (isBrsFile(file)) {
+				this.collectDefinitions(file);
+			} else if (isXmlFile(file)) {
+				this.collectXmlFile(file as XmlFile);
+			}
+		}
+
+		// Pass 2 – references (definitions must be complete before this runs)
+		for (const file of Object.values(program.files)) {
+			if (isBrsFile(file)) {
+				this.collectReferences(file);
+			}
+		}
+	}
+
+	// -------------------------------------------------------------------------
+	// Pass 1
+	// -------------------------------------------------------------------------
+
+	private collectDefinitions(file: BrsFile) {
+		file.ast.walk(createVisitor({
+			FunctionStatement: (stmt) => {
+				const name = stmt.getName(ParseMode.BrighterScript)?.toLowerCase();
+				if (name) {
+					this.allFunctions.set(name, { statement: stmt, file });
+					if (stmt.annotations?.find(a => a.name.toLowerCase() === 'keep')) {
+						this.keepAnnotated.add(name);
+					}
+				}
+			}
+		}), { walkMode: WalkMode.visitStatements });
+	}
+
+	private collectXmlFile(file: XmlFile) {
+		const component = file.parser.ast.component as any;
+
+		// Collect functions exposed through <interface><function name="..."/></interface>
+		if (Array.isArray(component?.api?.functions)) {
+			for (const func of component.api.functions) {
+				const name: string | undefined = func?.name;
+				if (name) {
+					this.xmlInterfaceFunctions.add(name.toLowerCase());
+				}
+			}
+		}
+
+		// Collect onChange="callbackName" from <interface><field onChange="..."/> elements.
+		// These are the most common observer callbacks in Roku components — they fire
+		// whenever the field value changes and are invisible to the BrightScript AST walker.
+		if (Array.isArray(component?.api?.fields)) {
+			for (const field of component.api.fields) {
+				const onChange: string | undefined = field?.onChange;
+				if (onChange && /^[a-z_][a-z0-9_.]*$/i.test(onChange)) {
+					this.xmlInterfaceFunctions.add(onChange.toLowerCase());
+				}
+			}
+		}
+
+		// Collect onChange="callbackName" attribute values from any element in the
+		// component <children> tree (e.g. inline node definitions with onChange set).
+		this.collectXmlOnChangeCallbacks(component?.children);
+	}
+
+	private collectXmlOnChangeCallbacks(children: any) {
+		if (!Array.isArray(children?.children)) {
+			return;
+		}
+		for (const child of children.children) {
+			if (Array.isArray(child.attributes)) {
+				for (const attr of child.attributes) {
+					const key: string | undefined = attr?.key?.text;
+					if (key?.toLowerCase() === 'onchange') {
+						const value: string | undefined = attr?.value?.text;
+						if (value && /^[a-z_][a-z0-9_.]*$/i.test(value)) {
+							this.xmlInterfaceFunctions.add(value.toLowerCase());
+						}
+					}
+				}
+			}
+			// Recurse into nested elements
+			this.collectXmlOnChangeCallbacks(child);
+		}
+	}
+
+	// -------------------------------------------------------------------------
+	// Pass 2
+	// -------------------------------------------------------------------------
+
+	private collectReferences(file: BrsFile) {
+		file.ast.walk(createVisitor({
+			CallExpression: (call) => {
+				const parts = util.getAllDottedGetParts(call.callee);
+				if (parts?.length) {
+					// Keep both the fully-qualified name and just the final segment
+					const full = parts.map(p => p.text).join('.').toLowerCase();
+					const simple = parts[parts.length - 1].text.toLowerCase();
+					this.calledNames.add(full);
+					this.calledNames.add(simple);
+				}
+			},
+
+			LiteralExpression: (expr) => {
+				if (isLiteralString(expr)) {
+					// Strip surrounding quotes and capture identifier-shaped strings.
+					// This conservatively retains functions referenced via observeField,
+					// callFunc, and similar dynamic dispatch patterns.
+					const raw = expr.token.text ?? '';
+					const text = raw.length >= 2 ? raw.slice(1, -1).toLowerCase() : '';
+					if (text && /^[a-z_][a-z0-9_.]*$/.test(text)) {
+						this.stringRefs.add(text);
+					}
+				}
+			},
+
+			VariableExpression: (expr) => {
+				// Detect simple function-reference patterns such as:
+				//   sgnode.observe(node, "field", onContentChanged)
+				//   callbacks = [onFoo, onBar]
+				// where the function is passed by reference rather than called or
+				// named as a string.  We only check names that are actually defined
+				// functions to avoid bloating calledNames with every local variable.
+				const name = (expr as any).name?.text?.toLowerCase();
+				if (name && this.allFunctions.has(name)) {
+					this.calledNames.add(name);
+				}
+			},
+
+			DottedGetExpression: (expr) => {
+				// Detect namespaced function-reference patterns such as:
+				//   sgnode.observe(node, "field", myNs.onContentChanged)
+				// The node is not a CallExpression callee here, so it would
+				// otherwise be invisible to the CallExpression walker above.
+				if (!isDottedGetExpression(expr)) {
+					return;
+				}
+				const parts = util.getAllDottedGetParts(expr);
+				if (parts?.length) {
+					const full = parts.map(p => p.text).join('.').toLowerCase();
+					const simple = parts[parts.length - 1].text.toLowerCase();
+					if (this.allFunctions.has(full) || this.allFunctions.has(simple)) {
+						this.calledNames.add(full);
+						this.calledNames.add(simple);
+					}
+				}
+			},
+
+			CallfuncExpression: (expr) => {
+				// Detect the @. callFunc shorthand:
+				//   m.blockContainer@.renderBlocks(blocksToRender)
+				// This is a CallfuncExpression, not a CallExpression, so the
+				// CallExpression visitor above never sees the method name.
+				const name = (expr as unknown as CallfuncExpression).methodName?.text?.toLowerCase();
+				if (name) {
+					this.calledNames.add(name);
+				}
+			}
+		}), { walkMode: WalkMode.visitAllRecursive });
+	}
+
+	// -------------------------------------------------------------------------
+	// Decision
+	// -------------------------------------------------------------------------
+
+	/**
+	 * Returns true when the function with the given fully-qualified lowercased name
+	 * has no known callers and is not a recognised entry point.
+	 */
+	isUnused(qualifiedName: string): boolean {
+		const simpleName = qualifiedName.split('.').pop() ?? qualifiedName;
+		return (
+			!this.keepAnnotated.has(qualifiedName) &&
+			!this.keepAnnotated.has(simpleName) &&
+			!TreeShaker.ENTRY_POINTS.has(simpleName) &&
+			!TreeShaker.ENTRY_POINTS.has(qualifiedName) &&
+			!this.calledNames.has(qualifiedName) &&
+			!this.calledNames.has(simpleName) &&
+			!this.stringRefs.has(qualifiedName) &&
+			!this.stringRefs.has(simpleName) &&
+			!this.xmlInterfaceFunctions.has(qualifiedName) &&
+			!this.xmlInterfaceFunctions.has(simpleName)
+		);
+	}
+
+	// -------------------------------------------------------------------------
+	// Shake
+	// -------------------------------------------------------------------------
+
+	/**
+	 * Walk the file and replace every unused FunctionStatement with an EmptyStatement,
+	 * effectively removing it from transpiled output.
+	 */
+	shake(file: BscFile, editor: AstEditor) {
+		if (!isBrsFile(file)) {
+			return;
+		}
+
+		file.ast.walk(createVisitor({
+			FunctionStatement: (stmt) => {
+				const name = stmt.getName(ParseMode.BrighterScript)?.toLowerCase();
+				if (name && this.isUnused(name)) {
+					return new EmptyStatement();
+				}
+			}
+		}), { walkMode: WalkMode.visitStatements, editor });
+	}
+}

From 022dd84d9167318c0bcd1d727c5d9b87440d6f0c Mon Sep 17 00:00:00 2001
From: Tyler Smith <tyler@tksssoftware.com>
Date: Wed, 18 Mar 2026 10:05:05 -0300
Subject: [PATCH 02/44] bsconfig control

---
 src/BsConfig.ts                             |  56 +-
 src/bscPlugin/BscPlugin.ts                  |   5 +-
 src/bscPlugin/treeShaker/TreeShaker.spec.ts | 361 ++++++++++++
 src/bscPlugin/treeShaker/TreeShaker.ts      | 594 +++++++++++---------
 src/util.ts                                 |  49 +-
 5 files changed, 801 insertions(+), 264 deletions(-)

diff --git a/src/BsConfig.ts b/src/BsConfig.ts
index 05cb40271..4ca44f679 100644
--- a/src/BsConfig.ts
+++ b/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 `true`.
+     */
+    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 };
diff --git a/src/bscPlugin/BscPlugin.ts b/src/bscPlugin/BscPlugin.ts
index 17df319bb..30d2deab1 100644
--- a/src/bscPlugin/BscPlugin.ts
+++ b/src/bscPlugin/BscPlugin.ts
@@ -65,7 +65,10 @@ export class BscPlugin implements Plugin {
     private treeShaker = new TreeShaker();
 
     public beforeProgramTranspile(program: Program, entries: TranspileObj[], editor: AstEditor) {
-        this.treeShaker.analyze(program);
+        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);
         }
diff --git a/src/bscPlugin/treeShaker/TreeShaker.spec.ts b/src/bscPlugin/treeShaker/TreeShaker.spec.ts
index ad819e401..698a23528 100644
--- a/src/bscPlugin/treeShaker/TreeShaker.spec.ts
+++ b/src/bscPlugin/treeShaker/TreeShaker.spec.ts
@@ -217,6 +217,22 @@ describe.only('TreeShakerValidator', () => {
             expect(code).not.to.include('sub unusedB()');
             expect(code).not.to.include('sub unusedC()');
         });
+
+        it('can be disabled via treeShaking.enabled = false', async () => {
+            program = new Program({ rootDir: rootDir, stagingDir: stagingDir, treeShaking: { enabled: false } });
+            program.setFile('source/main.bs', `
+                sub main()
+                end sub
+
+                sub unused()
+                    print "I should survive"
+                end sub
+            `);
+
+            const code = await getTranspiled('source/main.bs');
+            expect(code).to.include('sub main()');
+            expect(code).to.include('sub unused()');
+        });
     });
 
     describe('XML interface functions', () => {
@@ -274,4 +290,349 @@ describe.only('TreeShakerValidator', () => {
             expect(code).not.to.include('sub unused()');
         });
     });
+
+    describe('treeShaking.keep rules', () => {
+        describe('plain string entry', () => {
+            it('keeps a function matched by exact BrightScript name', async () => {
+                program = new Program({
+                    rootDir: rootDir, stagingDir: stagingDir,
+                    treeShaking: { keep: ['unusedHelper'] }
+                });
+                program.setFile('source/main.bs', `
+                    sub main()
+                    end sub
+
+                    sub unusedHelper()
+                        print "kept by string rule"
+                    end sub
+
+                    sub alsoUnused()
+                        print "not in keep list"
+                    end sub
+                `);
+
+                const code = await getTranspiled('source/main.bs');
+                expect(code).to.include('sub unusedHelper()');
+                expect(code).not.to.include('sub alsoUnused()');
+            });
+
+            it('keeps a namespaced function matched by BrightScript transpiled name', async () => {
+                program = new Program({
+                    rootDir: rootDir, stagingDir: stagingDir,
+                    treeShaking: { keep: ['utils_helper'] }
+                });
+                program.setFile('source/main.bs', `
+                    namespace utils
+                        sub helper()
+                            print "kept"
+                        end sub
+
+                        sub gone()
+                            print "removed"
+                        end sub
+                    end namespace
+
+                    sub main()
+                    end sub
+                `);
+
+                const code = await getTranspiled('source/main.bs');
+                expect(code).to.include('utils_helper');
+                expect(code).not.to.include('utils_gone');
+            });
+        });
+
+        describe('functions rule', () => {
+            it('keeps functions matched by exact name in functions array', async () => {
+                program = new Program({
+                    rootDir: rootDir, stagingDir: stagingDir,
+                    treeShaking: { keep: [{ functions: ['keepMe', 'alsoKeepMe'] }] }
+                });
+                program.setFile('source/main.bs', `
+                    sub main()
+                    end sub
+
+                    sub keepMe()
+                        print "kept"
+                    end sub
+
+                    sub alsoKeepMe()
+                        print "also kept"
+                    end sub
+
+                    sub removeMe()
+                        print "removed"
+                    end sub
+                `);
+
+                const code = await getTranspiled('source/main.bs');
+                expect(code).to.include('sub keepMe()');
+                expect(code).to.include('sub alsoKeepMe()');
+                expect(code).not.to.include('sub removeMe()');
+            });
+
+            it('is case-insensitive for function names', async () => {
+                program = new Program({
+                    rootDir: rootDir, stagingDir: stagingDir,
+                    treeShaking: { keep: [{ functions: ['UnusedHelper'] }] }
+                });
+                program.setFile('source/main.bs', `
+                    sub main()
+                    end sub
+
+                    sub unusedHelper()
+                        print "kept despite case difference"
+                    end sub
+                `);
+
+                const code = await getTranspiled('source/main.bs');
+                expect(code).to.include('sub unusedHelper()');
+            });
+        });
+
+        describe('matches rule', () => {
+            it('keeps functions matching a wildcard pattern', async () => {
+                program = new Program({
+                    rootDir: rootDir, stagingDir: stagingDir,
+                    treeShaking: { keep: [{ matches: ['rodash_*'] }] }
+                });
+                program.setFile('source/main.bs', `
+                    sub main()
+                    end sub
+
+                    sub rodash_tostring()
+                        print "matched by wildcard"
+                    end sub
+
+                    sub rodash_isarray()
+                        print "also matched"
+                    end sub
+
+                    sub unrelated()
+                        print "removed"
+                    end sub
+                `);
+
+                const code = await getTranspiled('source/main.bs');
+                expect(code).to.include('sub rodash_tostring()');
+                expect(code).to.include('sub rodash_isarray()');
+                expect(code).not.to.include('sub unrelated()');
+            });
+        });
+
+        describe('src rule', () => {
+            it('keeps all functions in files matching the src glob', async () => {
+                program = new Program({
+                    rootDir: rootDir, stagingDir: stagingDir,
+                    treeShaking: { keep: [{ src: 'source/vendor/**/*' }] }
+                });
+                program.setFile('source/vendor/lib.bs', `
+                    sub vendorHelper()
+                        print "from vendor"
+                    end sub
+
+                    sub anotherVendorFn()
+                        print "also from vendor"
+                    end sub
+                `);
+                program.setFile('source/main.bs', `
+                    sub main()
+                    end sub
+
+                    sub appHelper()
+                        print "app code - removed"
+                    end sub
+                `);
+
+                const vendorCode = await getTranspiled('source/vendor/lib.bs');
+                const mainCode = await getTranspiled('source/main.bs');
+
+                expect(vendorCode).to.include('sub vendorHelper()');
+                expect(vendorCode).to.include('sub anotherVendorFn()');
+                expect(mainCode).not.to.include('sub appHelper()');
+            });
+        });
+
+        describe('dest rule', () => {
+            it('keeps all functions in files matching the dest pkg path', async () => {
+                program = new Program({
+                    rootDir: rootDir, stagingDir: stagingDir,
+                    treeShaking: { keep: [{ dest: 'source/vendor/**/*' }] }
+                });
+                program.setFile('source/vendor/lib.bs', `
+                    sub vendorHelper()
+                        print "from vendor"
+                    end sub
+                `);
+                program.setFile('source/main.bs', `
+                    sub main()
+                    end sub
+
+                    sub appHelper()
+                        print "app code - removed"
+                    end sub
+                `);
+
+                const vendorCode = await getTranspiled('source/vendor/lib.bs');
+                const mainCode = await getTranspiled('source/main.bs');
+
+                expect(vendorCode).to.include('sub vendorHelper()');
+                expect(mainCode).not.to.include('sub appHelper()');
+            });
+        });
+
+        describe('combined AND rule', () => {
+            it('keeps only functions satisfying ALL fields in a single rule', async () => {
+                program = new Program({
+                    rootDir: rootDir, stagingDir: stagingDir,
+                    treeShaking: {
+                        keep: [{ src: 'source/lib.bs', functions: ['specialFn'] }]
+                    }
+                });
+                // specialFn in lib.bs — should be kept (matches both src AND functions)
+                program.setFile('source/lib.bs', `
+                    sub specialFn()
+                        print "kept — matches src AND functions"
+                    end sub
+
+                    sub otherFn()
+                        print "removed — matches src but not functions"
+                    end sub
+                `);
+                // specialFn in main.bs — should NOT be kept (matches functions but not src)
+                program.setFile('source/main.bs', `
+                    sub main()
+                    end sub
+
+                    sub specialFn()
+                        print "removed — matches functions but not src"
+                    end sub
+                `);
+
+                const libCode = await getTranspiled('source/lib.bs');
+                const mainCode = await getTranspiled('source/main.bs');
+
+                expect(libCode).to.include('sub specialFn()');
+                expect(libCode).not.to.include('sub otherFn()');
+                expect(mainCode).not.to.include('sub specialFn()');
+            });
+        });
+
+        describe('OR semantics across rules', () => {
+            it('keeps a function that matches any one of multiple rules', async () => {
+                program = new Program({
+                    rootDir: rootDir, stagingDir: stagingDir,
+                    treeShaking: {
+                        keep: [
+                            { functions: ['keepByName'] },
+                            { matches: ['keepBy*'] }
+                        ]
+                    }
+                });
+                program.setFile('source/main.bs', `
+                    sub main()
+                    end sub
+
+                    sub keepByName()
+                        print "kept by first rule"
+                    end sub
+
+                    sub keepByWildcard()
+                        print "kept by second rule"
+                    end sub
+
+                    sub removeMe()
+                        print "matches neither rule"
+                    end sub
+                `);
+
+                const code = await getTranspiled('source/main.bs');
+                expect(code).to.include('sub keepByName()');
+                expect(code).to.include('sub keepByWildcard()');
+                expect(code).not.to.include('sub removeMe()');
+            });
+        });
+
+        describe('scoped keep with same function name across files', () => {
+            it('only keeps the function in the matching source file', async () => {
+                program = new Program({
+                    rootDir: rootDir, stagingDir: stagingDir,
+                    treeShaking: {
+                        keep: [{ src: 'source/lib.bs', functions: ['sharedName'] }]
+                    }
+                });
+                program.setFile('source/lib.bs', `
+                    sub sharedName()
+                        print "in lib — kept"
+                    end sub
+                `);
+                program.setFile('source/other.bs', `
+                    sub sharedName()
+                        print "in other — removed"
+                    end sub
+                `);
+                program.setFile('source/main.bs', `
+                    sub main()
+                    end sub
+                `);
+
+                const libCode = await getTranspiled('source/lib.bs');
+                const otherCode = await getTranspiled('source/other.bs');
+
+                expect(libCode).to.include('sub sharedName()');
+                expect(otherCode).not.to.include('sub sharedName()');
+            });
+        });
+
+        describe('dependency closure', () => {
+            it('preserves transitive callees of a kept function', async () => {
+                program = new Program({
+                    rootDir: rootDir, stagingDir: stagingDir,
+                    treeShaking: { keep: ['topLevel'] }
+                });
+                program.setFile('source/main.bs', `
+                    sub main()
+                    end sub
+
+                    sub topLevel()
+                        innerHelper()
+                    end sub
+
+                    sub innerHelper()
+                        print "required by topLevel"
+                    end sub
+
+                    sub unrelated()
+                        print "no connection to topLevel"
+                    end sub
+                `);
+
+                const code = await getTranspiled('source/main.bs');
+                expect(code).to.include('sub topLevel()');
+                expect(code).to.include('sub innerHelper()');
+                expect(code).not.to.include('sub unrelated()');
+            });
+        });
+
+        describe('invalid rule validation', () => {
+            it('silently ignores object rules with no recognized fields', async () => {
+                // An empty object has no src/dest/functions/matches — should be skipped
+                program = new Program({
+                    rootDir: rootDir, stagingDir: stagingDir,
+                    treeShaking: { keep: [{} as any] }
+                });
+                program.setFile('source/main.bs', `
+                    sub main()
+                    end sub
+
+                    sub unused()
+                        print "still removed — empty rule is a no-op"
+                    end sub
+                `);
+
+                const code = await getTranspiled('source/main.bs');
+                expect(code).not.to.include('sub unused()');
+            });
+        });
+    });
 });
diff --git a/src/bscPlugin/treeShaker/TreeShaker.ts b/src/bscPlugin/treeShaker/TreeShaker.ts
index 8c27e28bb..aa23ddb68 100644
--- a/src/bscPlugin/treeShaker/TreeShaker.ts
+++ b/src/bscPlugin/treeShaker/TreeShaker.ts
@@ -1,8 +1,11 @@
+import * as minimatch from 'minimatch';
+import * as path from 'path';
 import type { AstEditor } from '../../astUtils/AstEditor';
 import { isBrsFile, isDottedGetExpression, isLiteralString, isXmlFile } from '../../astUtils/reflection';
 import { WalkMode, createVisitor } from '../../astUtils/visitors';
 import type { BrsFile } from '../../files/BrsFile';
 import type { XmlFile } from '../../files/XmlFile';
+import type { NormalizedKeepRule } from '../../BsConfig';
 import type { BscFile } from '../../interfaces';
 import type { CallfuncExpression } from '../../parser/Expression';
 import { ParseMode } from '../../parser/Parser';
@@ -12,263 +15,336 @@ import type { Program } from '../../Program';
 import util from '../../util';
 
 export class TreeShaker {
-	/**
-	 * Roku lifecycle callbacks and framework entry points that must always be kept.
-	 * These are never removed regardless of whether they appear in call expressions.
-	 */
-	private static readonly ENTRY_POINTS = new Set([
-		'main',
-		'init',
-		'onkeyevent',
-		'onmessage',
-		'runuserinterface',
-		'runtask',
-	]);
-
-	// Fully-qualified lowercased function names → statement + file
-	private allFunctions = new Map<string, { statement: FunctionStatement; file: BrsFile }>();
-
-	// Names referenced in CallExpression nodes (both full namespaced and simple names)
-	private calledNames = new Set<string>();
-
-	// String literal values that look like identifiers (potential dynamic callFunc / observeField targets)
-	private stringRefs = new Set<string>();
-
-	// Functions declared in XML <interface><function name="..."/> elements
-	private xmlInterfaceFunctions = new Set<string>();
-
-	// Functions explicitly annotated with @keep — never removed regardless of references
-	private keepAnnotated = new Set<string>();
-
-	reset() {
-		this.allFunctions.clear();
-		this.calledNames.clear();
-		this.stringRefs.clear();
-		this.xmlInterfaceFunctions.clear();
-		this.keepAnnotated.clear();
-	}
-
-	/**
-	 * Two-pass analysis of the entire program:
-	 *
-	 * Pass 1 — collect every function definition so we have the complete set
-	 *           of names before any reference pass runs.
-	 *
-	 * Pass 2 — collect call sites, string literals (dynamic dispatch / observeField),
-	 *           and VariableExpression references.  The VariableExpression check is
-	 *           gated on the name matching a known function so that passing a function
-	 *           by reference (e.g. sgnode.observe(node, "field", onContentChanged))
-	 *           is detected even when the name never appears as a string literal or
-	 *           direct call.
-	 */
-	analyze(program: Program) {
-		this.reset();
-
-		// Pass 1 – definitions + XML interfaces
-		for (const file of Object.values(program.files)) {
-			if (isBrsFile(file)) {
-				this.collectDefinitions(file);
-			} else if (isXmlFile(file)) {
-				this.collectXmlFile(file as XmlFile);
-			}
-		}
-
-		// Pass 2 – references (definitions must be complete before this runs)
-		for (const file of Object.values(program.files)) {
-			if (isBrsFile(file)) {
-				this.collectReferences(file);
-			}
-		}
-	}
-
-	// -------------------------------------------------------------------------
-	// Pass 1
-	// -------------------------------------------------------------------------
-
-	private collectDefinitions(file: BrsFile) {
-		file.ast.walk(createVisitor({
-			FunctionStatement: (stmt) => {
-				const name = stmt.getName(ParseMode.BrighterScript)?.toLowerCase();
-				if (name) {
-					this.allFunctions.set(name, { statement: stmt, file });
-					if (stmt.annotations?.find(a => a.name.toLowerCase() === 'keep')) {
-						this.keepAnnotated.add(name);
-					}
-				}
-			}
-		}), { walkMode: WalkMode.visitStatements });
-	}
-
-	private collectXmlFile(file: XmlFile) {
-		const component = file.parser.ast.component as any;
-
-		// Collect functions exposed through <interface><function name="..."/></interface>
-		if (Array.isArray(component?.api?.functions)) {
-			for (const func of component.api.functions) {
-				const name: string | undefined = func?.name;
-				if (name) {
-					this.xmlInterfaceFunctions.add(name.toLowerCase());
-				}
-			}
-		}
-
-		// Collect onChange="callbackName" from <interface><field onChange="..."/> elements.
-		// These are the most common observer callbacks in Roku components — they fire
-		// whenever the field value changes and are invisible to the BrightScript AST walker.
-		if (Array.isArray(component?.api?.fields)) {
-			for (const field of component.api.fields) {
-				const onChange: string | undefined = field?.onChange;
-				if (onChange && /^[a-z_][a-z0-9_.]*$/i.test(onChange)) {
-					this.xmlInterfaceFunctions.add(onChange.toLowerCase());
-				}
-			}
-		}
-
-		// Collect onChange="callbackName" attribute values from any element in the
-		// component <children> tree (e.g. inline node definitions with onChange set).
-		this.collectXmlOnChangeCallbacks(component?.children);
-	}
-
-	private collectXmlOnChangeCallbacks(children: any) {
-		if (!Array.isArray(children?.children)) {
-			return;
-		}
-		for (const child of children.children) {
-			if (Array.isArray(child.attributes)) {
-				for (const attr of child.attributes) {
-					const key: string | undefined = attr?.key?.text;
-					if (key?.toLowerCase() === 'onchange') {
-						const value: string | undefined = attr?.value?.text;
-						if (value && /^[a-z_][a-z0-9_.]*$/i.test(value)) {
-							this.xmlInterfaceFunctions.add(value.toLowerCase());
-						}
-					}
-				}
-			}
-			// Recurse into nested elements
-			this.collectXmlOnChangeCallbacks(child);
-		}
-	}
-
-	// -------------------------------------------------------------------------
-	// Pass 2
-	// -------------------------------------------------------------------------
-
-	private collectReferences(file: BrsFile) {
-		file.ast.walk(createVisitor({
-			CallExpression: (call) => {
-				const parts = util.getAllDottedGetParts(call.callee);
-				if (parts?.length) {
-					// Keep both the fully-qualified name and just the final segment
-					const full = parts.map(p => p.text).join('.').toLowerCase();
-					const simple = parts[parts.length - 1].text.toLowerCase();
-					this.calledNames.add(full);
-					this.calledNames.add(simple);
-				}
-			},
-
-			LiteralExpression: (expr) => {
-				if (isLiteralString(expr)) {
-					// Strip surrounding quotes and capture identifier-shaped strings.
-					// This conservatively retains functions referenced via observeField,
-					// callFunc, and similar dynamic dispatch patterns.
-					const raw = expr.token.text ?? '';
-					const text = raw.length >= 2 ? raw.slice(1, -1).toLowerCase() : '';
-					if (text && /^[a-z_][a-z0-9_.]*$/.test(text)) {
-						this.stringRefs.add(text);
-					}
-				}
-			},
-
-			VariableExpression: (expr) => {
-				// Detect simple function-reference patterns such as:
-				//   sgnode.observe(node, "field", onContentChanged)
-				//   callbacks = [onFoo, onBar]
-				// where the function is passed by reference rather than called or
-				// named as a string.  We only check names that are actually defined
-				// functions to avoid bloating calledNames with every local variable.
-				const name = (expr as any).name?.text?.toLowerCase();
-				if (name && this.allFunctions.has(name)) {
-					this.calledNames.add(name);
-				}
-			},
-
-			DottedGetExpression: (expr) => {
-				// Detect namespaced function-reference patterns such as:
-				//   sgnode.observe(node, "field", myNs.onContentChanged)
-				// The node is not a CallExpression callee here, so it would
-				// otherwise be invisible to the CallExpression walker above.
-				if (!isDottedGetExpression(expr)) {
-					return;
-				}
-				const parts = util.getAllDottedGetParts(expr);
-				if (parts?.length) {
-					const full = parts.map(p => p.text).join('.').toLowerCase();
-					const simple = parts[parts.length - 1].text.toLowerCase();
-					if (this.allFunctions.has(full) || this.allFunctions.has(simple)) {
-						this.calledNames.add(full);
-						this.calledNames.add(simple);
-					}
-				}
-			},
-
-			CallfuncExpression: (expr) => {
-				// Detect the @. callFunc shorthand:
-				//   m.blockContainer@.renderBlocks(blocksToRender)
-				// This is a CallfuncExpression, not a CallExpression, so the
-				// CallExpression visitor above never sees the method name.
-				const name = (expr as unknown as CallfuncExpression).methodName?.text?.toLowerCase();
-				if (name) {
-					this.calledNames.add(name);
-				}
-			}
-		}), { walkMode: WalkMode.visitAllRecursive });
-	}
-
-	// -------------------------------------------------------------------------
-	// Decision
-	// -------------------------------------------------------------------------
-
-	/**
-	 * Returns true when the function with the given fully-qualified lowercased name
-	 * has no known callers and is not a recognised entry point.
-	 */
-	isUnused(qualifiedName: string): boolean {
-		const simpleName = qualifiedName.split('.').pop() ?? qualifiedName;
-		return (
-			!this.keepAnnotated.has(qualifiedName) &&
-			!this.keepAnnotated.has(simpleName) &&
-			!TreeShaker.ENTRY_POINTS.has(simpleName) &&
-			!TreeShaker.ENTRY_POINTS.has(qualifiedName) &&
-			!this.calledNames.has(qualifiedName) &&
-			!this.calledNames.has(simpleName) &&
-			!this.stringRefs.has(qualifiedName) &&
-			!this.stringRefs.has(simpleName) &&
-			!this.xmlInterfaceFunctions.has(qualifiedName) &&
-			!this.xmlInterfaceFunctions.has(simpleName)
-		);
-	}
-
-	// -------------------------------------------------------------------------
-	// Shake
-	// -------------------------------------------------------------------------
-
-	/**
-	 * Walk the file and replace every unused FunctionStatement with an EmptyStatement,
-	 * effectively removing it from transpiled output.
-	 */
-	shake(file: BscFile, editor: AstEditor) {
-		if (!isBrsFile(file)) {
-			return;
-		}
-
-		file.ast.walk(createVisitor({
-			FunctionStatement: (stmt) => {
-				const name = stmt.getName(ParseMode.BrighterScript)?.toLowerCase();
-				if (name && this.isUnused(name)) {
-					return new EmptyStatement();
-				}
-			}
-		}), { walkMode: WalkMode.visitStatements, editor });
-	}
+    /**
+     * Roku lifecycle callbacks and framework entry points that must always be kept.
+     * These are never removed regardless of whether they appear in call expressions.
+     */
+    private static readonly ENTRY_POINTS = new Set([
+        'main',
+        'init',
+        'onkeyevent',
+        'onmessage',
+        'runuserinterface',
+        'runtask'
+    ]);
+
+    // Fully-qualified lowercased function names (BrighterScript style, dots) → statement + file + brsName
+    private allFunctions = new Map<string, { statement: FunctionStatement; file: BrsFile; brsName: string }>();
+
+    // Names referenced in CallExpression nodes (both full namespaced and simple names)
+    private calledNames = new Set<string>();
+
+    // String literal values that look like identifiers (potential dynamic callFunc / observeField targets)
+    private stringRefs = new Set<string>();
+
+    // Functions declared in XML <interface><function name="..."/> elements
+    private xmlInterfaceFunctions = new Set<string>();
+
+    // Functions explicitly annotated with @keep — never removed regardless of references
+    private keepAnnotated = new Set<string>();
+
+    // Normalized keep rules from config
+    private keepRules: NormalizedKeepRule[] = [];
+
+    // Resolved rootDir for src-path matching
+    private rootDir = '';
+
+    reset() {
+        this.allFunctions.clear();
+        this.calledNames.clear();
+        this.stringRefs.clear();
+        this.xmlInterfaceFunctions.clear();
+        this.keepAnnotated.clear();
+        this.keepRules = [];
+        this.rootDir = '';
+    }
+
+    /**
+     * Two-pass analysis of the entire program:
+     *
+     * Pass 1 — collect every function definition so we have the complete set
+     *           of names before any reference pass runs.
+     *
+     * Pass 2 — collect call sites, string literals (dynamic dispatch / observeField),
+     *           and VariableExpression references.  The VariableExpression check is
+     *           gated on the name matching a known function so that passing a function
+     *           by reference (e.g. sgnode.observe(node, "field", onContentChanged))
+     *           is detected even when the name never appears as a string literal or
+     *           direct call.
+     */
+    analyze(program: Program, keepRules: NormalizedKeepRule[]) {
+        this.reset();
+        this.keepRules = keepRules;
+        this.rootDir = program.options.rootDir ?? process.cwd();
+
+        // Pass 1 – definitions + XML interfaces
+        for (const file of Object.values(program.files)) {
+            if (isBrsFile(file)) {
+                this.collectDefinitions(file);
+            } else if (isXmlFile(file)) {
+                this.collectXmlFile(file as XmlFile);
+            }
+        }
+
+        // Pass 2 – references (definitions must be complete before this runs)
+        for (const file of Object.values(program.files)) {
+            if (isBrsFile(file)) {
+                this.collectReferences(file);
+            }
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Pass 1
+    // -------------------------------------------------------------------------
+
+    private collectDefinitions(file: BrsFile) {
+        file.ast.walk(createVisitor({
+            FunctionStatement: (stmt) => {
+                const bsName = stmt.getName(ParseMode.BrighterScript)?.toLowerCase();
+                const brsName = stmt.getName(ParseMode.BrightScript)?.toLowerCase();
+                if (bsName && brsName) {
+                    this.allFunctions.set(bsName, { statement: stmt, file: file, brsName: brsName });
+                    if (stmt.annotations?.find(a => a.name.toLowerCase() === 'keep')) {
+                        this.keepAnnotated.add(bsName);
+                    }
+                }
+            }
+        }), { walkMode: WalkMode.visitStatements });
+    }
+
+    private collectXmlFile(file: XmlFile) {
+        const component = file.parser.ast.component as any;
+
+        // Collect functions exposed through <interface><function name="..."/></interface>
+        if (Array.isArray(component?.api?.functions)) {
+            for (const func of component.api.functions) {
+                const name: string | undefined = func?.name;
+                if (name) {
+                    this.xmlInterfaceFunctions.add(name.toLowerCase());
+                }
+            }
+        }
+
+        // Collect onChange="callbackName" from <interface><field onChange="..."/> elements.
+        // These are the most common observer callbacks in Roku components — they fire
+        // whenever the field value changes and are invisible to the BrightScript AST walker.
+        if (Array.isArray(component?.api?.fields)) {
+            for (const field of component.api.fields) {
+                const onChange: string | undefined = field?.onChange;
+                if (onChange && /^[a-z_][a-z0-9_.]*$/i.test(onChange)) {
+                    this.xmlInterfaceFunctions.add(onChange.toLowerCase());
+                }
+            }
+        }
+
+        // Collect onChange="callbackName" attribute values from any element in the
+        // component <children> tree (e.g. inline node definitions with onChange set).
+        this.collectXmlOnChangeCallbacks(component?.children);
+    }
+
+    private collectXmlOnChangeCallbacks(children: any) {
+        if (!Array.isArray(children?.children)) {
+            return;
+        }
+        for (const child of children.children) {
+            if (Array.isArray(child.attributes)) {
+                for (const attr of child.attributes) {
+                    const key: string | undefined = attr?.key?.text;
+                    if (key?.toLowerCase() === 'onchange') {
+                        const value: string | undefined = attr?.value?.text;
+                        if (value && /^[a-z_][a-z0-9_.]*$/i.test(value)) {
+                            this.xmlInterfaceFunctions.add(value.toLowerCase());
+                        }
+                    }
+                }
+            }
+            // Recurse into nested elements
+            this.collectXmlOnChangeCallbacks(child);
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Pass 2
+    // -------------------------------------------------------------------------
+
+    private collectReferences(file: BrsFile) {
+        file.ast.walk(createVisitor({
+            CallExpression: (call) => {
+                const parts = util.getAllDottedGetParts(call.callee);
+                if (parts?.length) {
+                    // Keep both the fully-qualified name and just the final segment
+                    const full = parts.map(p => p.text).join('.').toLowerCase();
+                    const simple = parts[parts.length - 1].text.toLowerCase();
+                    this.calledNames.add(full);
+                    this.calledNames.add(simple);
+                }
+            },
+
+            LiteralExpression: (expr) => {
+                if (isLiteralString(expr)) {
+                    // Strip surrounding quotes and capture identifier-shaped strings.
+                    // This conservatively retains functions referenced via observeField,
+                    // callFunc, and similar dynamic dispatch patterns.
+                    const raw = expr.token.text ?? '';
+                    const text = raw.length >= 2 ? raw.slice(1, -1).toLowerCase() : '';
+                    if (text && /^[a-z_][a-z0-9_.]*$/.test(text)) {
+                        this.stringRefs.add(text);
+                    }
+                }
+            },
+
+            VariableExpression: (expr) => {
+                // Detect simple function-reference patterns such as:
+                //   sgnode.observe(node, "field", onContentChanged)
+                //   callbacks = [onFoo, onBar]
+                // where the function is passed by reference rather than called or
+                // named as a string.  We only check names that are actually defined
+                // functions to avoid bloating calledNames with every local variable.
+                const name = (expr as any).name?.text?.toLowerCase();
+                if (name && this.allFunctions.has(name)) {
+                    this.calledNames.add(name);
+                }
+            },
+
+            DottedGetExpression: (expr) => {
+                // Detect namespaced function-reference patterns such as:
+                //   sgnode.observe(node, "field", myNs.onContentChanged)
+                // The node is not a CallExpression callee here, so it would
+                // otherwise be invisible to the CallExpression walker above.
+                if (!isDottedGetExpression(expr)) {
+                    return;
+                }
+                const parts = util.getAllDottedGetParts(expr);
+                if (parts?.length) {
+                    const full = parts.map(p => p.text).join('.').toLowerCase();
+                    const simple = parts[parts.length - 1].text.toLowerCase();
+                    if (this.allFunctions.has(full) || this.allFunctions.has(simple)) {
+                        this.calledNames.add(full);
+                        this.calledNames.add(simple);
+                    }
+                }
+            },
+
+            CallfuncExpression: (expr) => {
+                // Detect the @. callFunc shorthand:
+                //   m.blockContainer@.renderBlocks(blocksToRender)
+                // This is a CallfuncExpression, not a CallExpression, so the
+                // CallExpression visitor above never sees the method name.
+                const name = (expr as unknown as CallfuncExpression).methodName?.text?.toLowerCase();
+                if (name) {
+                    this.calledNames.add(name);
+                }
+            }
+        }), { walkMode: WalkMode.visitAllRecursive });
+    }
+
+    // -------------------------------------------------------------------------
+    // Decision
+    // -------------------------------------------------------------------------
+
+    /**
+     * Returns true when the function with the given fully-qualified lowercased name
+     * has no known callers and is not a recognized entry point.
+     */
+    isUnused(bsName: string): boolean {
+        const simpleName = bsName.split('.').pop() ?? bsName;
+        return (
+            !this.keepAnnotated.has(bsName) &&
+            !this.keepAnnotated.has(simpleName) &&
+            !TreeShaker.ENTRY_POINTS.has(simpleName) &&
+            !TreeShaker.ENTRY_POINTS.has(bsName) &&
+            !this.calledNames.has(bsName) &&
+            !this.calledNames.has(simpleName) &&
+            !this.stringRefs.has(bsName) &&
+            !this.stringRefs.has(simpleName) &&
+            !this.xmlInterfaceFunctions.has(bsName) &&
+            !this.xmlInterfaceFunctions.has(simpleName)
+        );
+    }
+
+    /**
+     * Returns true when the function matches any keep rule from config.
+     * Rule fields are ANDed; rules across the list are ORed.
+     */
+    isKept(bsName: string, brsName: string, file: BrsFile): boolean {
+        for (const rule of this.keepRules) {
+            if (this.ruleMatches(rule, brsName, file)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    private ruleMatches(rule: NormalizedKeepRule, brsName: string, file: BrsFile): boolean {
+        // functions: exact name match (BrightScript/transpiled names)
+        if (rule.functions) {
+            if (!rule.functions.includes(brsName)) {
+                return false;
+            }
+        }
+
+        // matches: glob/wildcard against function name
+        if (rule.matches) {
+            const matched = rule.matches.some(pattern => minimatch(brsName, pattern, { nocase: true })
+            );
+            if (!matched) {
+                return false;
+            }
+        }
+
+        // src: glob against source file path (relative patterns resolved from rootDir)
+        if (rule.src) {
+            const srcPath = file.srcPath;
+            const matched = rule.src.some(pattern => {
+                const resolved = path.isAbsolute(pattern)
+                    ? pattern
+                    : `${this.rootDir}/${pattern}`;
+                return minimatch(srcPath, resolved, { nocase: true });
+            });
+            if (!matched) {
+                return false;
+            }
+        }
+
+        // dest: glob against package-relative destination path (pkgPath)
+        if (rule.dest) {
+            const pkgPath = file.pkgPath;
+            const matched = rule.dest.some(pattern => minimatch(pkgPath, pattern, { nocase: true })
+            );
+            if (!matched) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+    // -------------------------------------------------------------------------
+    // Shake
+    // -------------------------------------------------------------------------
+
+    /**
+     * Walk the file and replace every unused FunctionStatement with an EmptyStatement,
+     * effectively removing it from transpiled output.
+     */
+    shake(file: BscFile, editor: AstEditor) {
+        if (!isBrsFile(file)) {
+            return;
+        }
+
+        file.ast.walk(createVisitor({
+            FunctionStatement: (stmt) => {
+                const bsName = stmt.getName(ParseMode.BrighterScript)?.toLowerCase();
+                if (!bsName) {
+                    return;
+                }
+                const entry = this.allFunctions.get(bsName);
+                const brsName = entry?.brsName ?? bsName;
+                if (this.isUnused(bsName) && !this.isKept(bsName, brsName, file)) {
+                    return new EmptyStatement();
+                }
+            }
+        }), { walkMode: WalkMode.visitStatements, editor: editor });
+    }
 }
diff --git a/src/util.ts b/src/util.ts
index db38cfd28..ba42cf2c5 100644
--- a/src/util.ts
+++ b/src/util.ts
@@ -7,7 +7,7 @@ import { rokuDeploy, DefaultFiles } from 'roku-deploy';
 import type { Diagnostic, Position, Range, Location, DiagnosticRelatedInformation } from 'vscode-languageserver';
 import { URI } from 'vscode-uri';
 import * as xml2js from 'xml2js';
-import type { BsConfig, FinalizedBsConfig } from './BsConfig';
+import type { BsConfig, FinalizedBsConfig, NormalizedKeepRule, NormalizedTreeShakingConfig, TreeShakingConfig, TreeShakingKeepEntry } from './BsConfig';
 import { DiagnosticMessages } from './DiagnosticMessages';
 import type { CallableContainer, BsDiagnostic, FileReference, CallableContainerMap, Plugin, ExpressionInfo, TranspileResult, MaybePromise, DisposableLike, PluginFactory } from './interfaces';
 import { BooleanType } from './types/BooleanType';
@@ -403,7 +403,8 @@ export class Util {
             emitDefinitions: config.emitDefinitions === true ? true : false,
             removeParameterTypes: config.removeParameterTypes === true ? true : false,
             logLevel: logLevel,
-            bslibDestinationDir: bslibDestinationDir
+            bslibDestinationDir: bslibDestinationDir,
+            treeShaking: this.normalizeTreeShakingConfig(config.treeShaking)
         };
 
         //mutate `config` in case anyone is holding a reference to the incomplete one
@@ -412,6 +413,50 @@ export class Util {
         return merged;
     }
 
+    /**
+     * Normalize `treeShaking` config into the internal `NormalizedTreeShakingConfig` form.
+     * - Plain strings are expanded to `{ functions: [string] }`.
+     * - Scalar `src`/`dest`/`functions`/`matches` values are wrapped in arrays.
+     * - Object rules that contain none of the known fields are silently skipped.
+     */
+    private normalizeTreeShakingConfig(config?: TreeShakingConfig): NormalizedTreeShakingConfig {
+        const enabled = config?.enabled !== false;
+        const keep: NormalizedKeepRule[] = [];
+
+        for (const entry of (config?.keep ?? []) as TreeShakingKeepEntry[]) {
+            if (typeof entry === 'string') {
+                keep.push({ functions: [entry.toLowerCase()] });
+            } else if (entry && typeof entry === 'object') {
+                const hasField =
+                    entry.src !== undefined ||
+                    entry.dest !== undefined ||
+                    entry.functions !== undefined ||
+                    entry.matches !== undefined;
+                if (!hasField) {
+                    // Invalid rule — no recognized field present; skip silently
+                    continue;
+                }
+                const rule: NormalizedKeepRule = {};
+                if (entry.src !== undefined) {
+                    rule.src = Array.isArray(entry.src) ? entry.src : [entry.src];
+                }
+                if (entry.dest !== undefined) {
+                    rule.dest = Array.isArray(entry.dest) ? entry.dest : [entry.dest];
+                }
+                if (entry.functions !== undefined) {
+                    rule.functions = (Array.isArray(entry.functions) ? entry.functions : [entry.functions])
+                        .map(f => f.toLowerCase());
+                }
+                if (entry.matches !== undefined) {
+                    rule.matches = Array.isArray(entry.matches) ? entry.matches : [entry.matches];
+                }
+                keep.push(rule);
+            }
+        }
+
+        return { enabled: enabled, keep: keep };
+    }
+
     /**
      * Get the root directory from options.
      * Falls back to options.cwd.

From f04302edd07fde684d366b1af0f1b8f8d798351a Mon Sep 17 00:00:00 2001
From: Tyler Smith <tyler@tksssoftware.com>
Date: Wed, 18 Mar 2026 10:37:44 -0300
Subject: [PATCH 03/44] Change from annotation to comments

---
 src/bscPlugin/treeShaker/TreeShaker.spec.ts | 69 +++++++++++++++++++--
 src/bscPlugin/treeShaker/TreeShaker.ts      | 46 +++++++++++---
 src/files/BrsFile.ts                        | 22 +++++++
 3 files changed, 124 insertions(+), 13 deletions(-)

diff --git a/src/bscPlugin/treeShaker/TreeShaker.spec.ts b/src/bscPlugin/treeShaker/TreeShaker.spec.ts
index 698a23528..c84a9dedf 100644
--- a/src/bscPlugin/treeShaker/TreeShaker.spec.ts
+++ b/src/bscPlugin/treeShaker/TreeShaker.spec.ts
@@ -4,7 +4,7 @@ import { standardizePath as s } from '../../util';
 import * as fsExtra from 'fs-extra';
 import undent from 'undent';
 
-describe.only('TreeShakerValidator', () => {
+describe('TreeShakerValidator', () => {
     let program: Program;
     const tempDir = s`${__dirname}/../.tmp`;
     const rootDir = s`${tempDir}/rootDir`;
@@ -97,18 +97,37 @@ describe.only('TreeShakerValidator', () => {
             expect(code).not.to.include('sub removable()');
         });
 
-        it('preserves @keep annotated functions regardless of call sites', async () => {
+        it('preserves functions with a bs:keep comment on the same line', async () => {
             program.setFile('source/main.bs', `
                 sub main()
                 end sub
 
-                @keep
+                sub mustStay() ' bs:keep
+                    print "inline keep comment"
+                end sub
+
+                sub canGo()
+                    print "no keep comment"
+                end sub
+            `);
+
+            const code = await getTranspiled('source/main.bs');
+            expect(code).to.include('sub mustStay()');
+            expect(code).not.to.include('sub canGo()');
+        });
+
+        it('preserves functions with a bs:keep comment on the line above', async () => {
+            program.setFile('source/main.bs', `
+                sub main()
+                end sub
+
+                ' bs:keep
                 sub mustStay()
-                    print "annotated with keep"
+                    print "keep comment above"
                 end sub
 
                 sub canGo()
-                    print "no annotation"
+                    print "no keep comment"
                 end sub
             `);
 
@@ -117,6 +136,46 @@ describe.only('TreeShakerValidator', () => {
             expect(code).not.to.include('sub canGo()');
         });
 
+        it('preserves functions with a bs:keep comment anywhere between the previous function and this one', async () => {
+            program.setFile('source/main.bs', `
+                sub main()
+                end sub
+
+                ' some description
+                ' bs:keep
+                ' another comment
+                sub mustStay()
+                    print "keep comment in header region"
+                end sub
+
+                sub canGo()
+                end sub
+            `);
+
+            const code = await getTranspiled('source/main.bs');
+            expect(code).to.include('sub mustStay()');
+            expect(code).not.to.include('sub canGo()');
+        });
+
+        it('does not apply a bs:keep comment to the function before it', async () => {
+            program.setFile('source/main.bs', `
+                sub main()
+                end sub
+
+                sub shouldBeRemoved()
+                    print "no keep"
+                end sub
+
+                ' bs:keep
+                sub mustStay()
+                end sub
+            `);
+
+            const code = await getTranspiled('source/main.bs');
+            expect(code).not.to.include('sub shouldBeRemoved()');
+            expect(code).to.include('sub mustStay()');
+        });
+
         it('preserves functions referenced as string literals (observeField pattern)', async () => {
             program.setFile('source/main.bs', `
                 sub init()
diff --git a/src/bscPlugin/treeShaker/TreeShaker.ts b/src/bscPlugin/treeShaker/TreeShaker.ts
index aa23ddb68..cf803c819 100644
--- a/src/bscPlugin/treeShaker/TreeShaker.ts
+++ b/src/bscPlugin/treeShaker/TreeShaker.ts
@@ -40,8 +40,8 @@ export class TreeShaker {
     // Functions declared in XML <interface><function name="..."/> elements
     private xmlInterfaceFunctions = new Set<string>();
 
-    // Functions explicitly annotated with @keep — never removed regardless of references
-    private keepAnnotated = new Set<string>();
+    // Functions marked with a `bs:keep` comment — never removed regardless of references
+    private keepCommented = new Set<string>();
 
     // Normalized keep rules from config
     private keepRules: NormalizedKeepRule[] = [];
@@ -54,7 +54,7 @@ export class TreeShaker {
         this.calledNames.clear();
         this.stringRefs.clear();
         this.xmlInterfaceFunctions.clear();
-        this.keepAnnotated.clear();
+        this.keepCommented.clear();
         this.keepRules = [];
         this.rootDir = '';
     }
@@ -99,18 +99,48 @@ export class TreeShaker {
     // -------------------------------------------------------------------------
 
     private collectDefinitions(file: BrsFile) {
+        // Collect all function statements first so we can sort by source order.
+        // Sorting is required for the prev-end-line region check used by `bs:keep`.
+        const collected: Array<{ bsName: string; brsName: string; stmt: FunctionStatement }> = [];
+
         file.ast.walk(createVisitor({
             FunctionStatement: (stmt) => {
                 const bsName = stmt.getName(ParseMode.BrighterScript)?.toLowerCase();
                 const brsName = stmt.getName(ParseMode.BrightScript)?.toLowerCase();
                 if (bsName && brsName) {
                     this.allFunctions.set(bsName, { statement: stmt, file: file, brsName: brsName });
-                    if (stmt.annotations?.find(a => a.name.toLowerCase() === 'keep')) {
-                        this.keepAnnotated.add(bsName);
-                    }
+                    collected.push({ bsName: bsName, brsName: brsName, stmt: stmt });
                 }
             }
         }), { walkMode: WalkMode.visitStatements });
+
+        // Walk functions in source order to detect `bs:keep` comments.
+        // A `bs:keep` on line N applies to a function F when:
+        //   • N == F.startLine  (same-line inline comment), OR
+        //   • prevFunctionEndLine < N <= F.startLine  (comment in the header region above F)
+        collected.sort((a, b) => a.stmt.range.start.line - b.stmt.range.start.line);
+
+        let prevEndLine = -1;
+        for (const { bsName, stmt } of collected) {
+            const startLine = stmt.range.start.line;
+            if (this.hasBsKeepInRegion(file, prevEndLine, startLine)) {
+                this.keepCommented.add(bsName);
+            }
+            prevEndLine = stmt.range.end.line;
+        }
+    }
+
+    /**
+     * Returns true if any `bs:keep` comment line falls in the half-open interval
+     * (prevEndLine, functionStartLine] — i.e., in the "header region" above a function.
+     */
+    private hasBsKeepInRegion(file: BrsFile, prevEndLine: number, functionStartLine: number): boolean {
+        for (const line of file.keepFlagLines) {
+            if (line > prevEndLine && line <= functionStartLine) {
+                return true;
+            }
+        }
+        return false;
     }
 
     private collectXmlFile(file: XmlFile) {
@@ -250,8 +280,8 @@ export class TreeShaker {
     isUnused(bsName: string): boolean {
         const simpleName = bsName.split('.').pop() ?? bsName;
         return (
-            !this.keepAnnotated.has(bsName) &&
-            !this.keepAnnotated.has(simpleName) &&
+            !this.keepCommented.has(bsName) &&
+            !this.keepCommented.has(simpleName) &&
             !TreeShaker.ENTRY_POINTS.has(simpleName) &&
             !TreeShaker.ENTRY_POINTS.has(bsName) &&
             !this.calledNames.has(bsName) &&
diff --git a/src/files/BrsFile.ts b/src/files/BrsFile.ts
index d8b86cf45..41384f8bf 100644
--- a/src/files/BrsFile.ts
+++ b/src/files/BrsFile.ts
@@ -142,6 +142,14 @@ export class BrsFile {
 
     public commentFlags = [] as CommentFlag[];
 
+    /**
+     * Line numbers that have a `bs:keep` comment. Used by the tree shaker to
+     * preserve functions that are annotated with this comment either on the
+     * same line as the `sub`/`function` keyword or anywhere between the end of
+     * the previous function and the start of this one.
+     */
+    public keepFlagLines = new Set<number>();
+
     public callables = [] as Callable[];
 
     public functionCalls = [] as FunctionCall[];
@@ -443,9 +451,13 @@ export class BrsFile {
         const processor = new CommentFlagProcessor(this, ['rem', `'`], diagnosticCodes, [DiagnosticCodeMap.unknownDiagnosticCode]);
 
         this.commentFlags = [];
+        this.keepFlagLines = new Set<number>();
         for (let token of tokens) {
             if (token.kind === TokenKind.Comment) {
                 processor.tryAdd(token.text, token.range);
+                if (isBsKeepComment(token.text)) {
+                    this.keepFlagLines.add(token.range.start.line);
+                }
             }
         }
         this.commentFlags.push(...processor.commentFlags);
@@ -1453,3 +1465,13 @@ export const KeywordCompletions = Object.keys(Keywords)
             kind: CompletionItemKind.Keyword
         } as CompletionItem;
     });
+
+/**
+ * Returns true if the raw comment token text contains a `bs:keep` directive.
+ * Handles both `'` and `rem` starters, with optional leading whitespace.
+ */
+function isBsKeepComment(text: string): boolean {
+    // Strip the comment starter (`'` or `rem`) then check for `bs:keep`
+    const lower = text.toLowerCase().replace(/^(?:rem|')/, '').trimLeft();
+    return lower.startsWith('bs:keep');
+}

From 0ab9294f3449150c12469a18aa5668e0156017d2 Mon Sep 17 00:00:00 2001
From: Tyler Smith <tyler@tksssoftware.com>
Date: Wed, 18 Mar 2026 10:43:33 -0300
Subject: [PATCH 04/44] spec update

---
 src/bscPlugin/treeShaker/TreeShaker.spec.ts | 241 ++++++++++++++++++++
 1 file changed, 241 insertions(+)

diff --git a/src/bscPlugin/treeShaker/TreeShaker.spec.ts b/src/bscPlugin/treeShaker/TreeShaker.spec.ts
index c84a9dedf..e70476d93 100644
--- a/src/bscPlugin/treeShaker/TreeShaker.spec.ts
+++ b/src/bscPlugin/treeShaker/TreeShaker.spec.ts
@@ -157,6 +157,77 @@ describe('TreeShakerValidator', () => {
             expect(code).not.to.include('sub canGo()');
         });
 
+        it('preserves the first function in a file with bs:keep (no previous function)', async () => {
+            program.setFile('source/main.bs', `
+                ' bs:keep
+                sub firstFunction()
+                    print "first function, no prev end line"
+                end sub
+
+                sub main()
+                end sub
+            `);
+
+            const code = await getTranspiled('source/main.bs');
+            expect(code).to.include('sub firstFunction()');
+        });
+
+        it('does not treat a bs:keep inside a function body as a header comment', async () => {
+            program.setFile('source/main.bs', `
+                sub main()
+                    ' bs:keep
+                    print "comment inside body"
+                end sub
+
+                sub shouldBeRemoved()
+                end sub
+            `);
+
+            const code = await getTranspiled('source/main.bs');
+            expect(code).not.to.include('sub shouldBeRemoved()');
+        });
+
+        it('preserves a namespaced function with a bs:keep comment', async () => {
+            program.setFile('source/main.bs', `
+                namespace utils
+                    ' bs:keep
+                    sub keepMe()
+                        print "namespaced, kept by comment"
+                    end sub
+
+                    sub removeMe()
+                        print "namespaced, no keep"
+                    end sub
+                end namespace
+
+                sub main()
+                end sub
+            `);
+
+            const code = await getTranspiled('source/main.bs');
+            expect(code).to.include('utils_keepMe');
+            expect(code).not.to.include('utils_removeMe');
+        });
+
+        it('supports bs:keep with rem comment syntax', async () => {
+            program.setFile('source/main.bs', `
+                sub main()
+                end sub
+
+                rem bs:keep
+                sub mustStay()
+                    print "kept via rem"
+                end sub
+
+                sub canGo()
+                end sub
+            `);
+
+            const code = await getTranspiled('source/main.bs');
+            expect(code).to.include('sub mustStay()');
+            expect(code).not.to.include('sub canGo()');
+        });
+
         it('does not apply a bs:keep comment to the function before it', async () => {
             program.setFile('source/main.bs', `
                 sub main()
@@ -277,6 +348,94 @@ describe('TreeShakerValidator', () => {
             expect(code).not.to.include('sub unusedC()');
         });
 
+        it('preserves functions across files when called from another file', async () => {
+            program.setFile('source/utils.bs', `
+                sub utilHelper()
+                    print "used from main"
+                end sub
+
+                sub unusedUtil()
+                    print "never called"
+                end sub
+            `);
+            program.setFile('source/main.bs', `
+                sub main()
+                    utilHelper()
+                end sub
+            `);
+
+            const utilCode = await getTranspiled('source/utils.bs');
+            expect(utilCode).to.include('sub utilHelper()');
+            expect(utilCode).not.to.include('sub unusedUtil()');
+        });
+
+        it('preserves function keyword declarations (not just sub)', async () => {
+            program.setFile('source/main.bs', `
+                sub main()
+                    print compute()
+                end sub
+
+                function compute() as integer
+                    return 42
+                end function
+
+                function unused() as integer
+                    return 0
+                end function
+            `);
+
+            const code = await getTranspiled('source/main.bs');
+            expect(code).to.include('function compute()');
+            expect(code).not.to.include('function unused()');
+        });
+
+        it('preserves indirect callees via a call chain (main → A → B)', async () => {
+            program.setFile('source/main.bs', `
+                sub main()
+                    stepA()
+                end sub
+
+                sub stepA()
+                    stepB()
+                end sub
+
+                sub stepB()
+                    print "end of chain"
+                end sub
+
+                sub unused()
+                end sub
+            `);
+
+            const code = await getTranspiled('source/main.bs');
+            expect(code).to.include('sub stepA()');
+            expect(code).to.include('sub stepB()');
+            expect(code).not.to.include('sub unused()');
+        });
+
+        it('conservatively preserves a function called only from dead code', async () => {
+            // The reference pass walks ALL bodies including dead ones, so callee of
+            // a dead function ends up in calledNames and is kept. This is intentional
+            // conservative behaviour — it avoids false removals at the cost of a
+            // slightly larger output.
+            program.setFile('source/main.bs', `
+                sub main()
+                end sub
+
+                sub deadCaller()
+                    calledFromDead()
+                end sub
+
+                sub calledFromDead()
+                    print "kept because reference pass sees the call in deadCaller"
+                end sub
+            `);
+
+            const code = await getTranspiled('source/main.bs');
+            expect(code).not.to.include('sub deadCaller()');
+            expect(code).to.include('sub calledFromDead()');
+        });
+
         it('can be disabled via treeShaking.enabled = false', async () => {
             program = new Program({ rootDir: rootDir, stagingDir: stagingDir, treeShaking: { enabled: false } });
             program.setFile('source/main.bs', `
@@ -673,6 +832,88 @@ describe('TreeShakerValidator', () => {
             });
         });
 
+        describe('matches with multiple patterns', () => {
+            it('keeps functions matching any pattern in the matches array', async () => {
+                program = new Program({
+                    rootDir: rootDir, stagingDir: stagingDir,
+                    treeShaking: { keep: [{ matches: ['foo_*', 'bar_*'] }] }
+                });
+                program.setFile('source/main.bs', `
+                    sub main()
+                    end sub
+
+                    sub foo_helper()
+                        print "matches foo_*"
+                    end sub
+
+                    sub bar_helper()
+                        print "matches bar_*"
+                    end sub
+
+                    sub baz_helper()
+                        print "matches neither"
+                    end sub
+                `);
+
+                const code = await getTranspiled('source/main.bs');
+                expect(code).to.include('sub foo_helper()');
+                expect(code).to.include('sub bar_helper()');
+                expect(code).not.to.include('sub baz_helper()');
+            });
+        });
+
+        describe('src with array of globs', () => {
+            it('keeps functions from any matching source path', async () => {
+                program = new Program({
+                    rootDir: rootDir, stagingDir: stagingDir,
+                    treeShaking: { keep: [{ src: ['source/libA.bs', 'source/libB.bs'] }] }
+                });
+                program.setFile('source/libA.bs', `
+                    sub fromA()
+                    end sub
+                `);
+                program.setFile('source/libB.bs', `
+                    sub fromB()
+                    end sub
+                `);
+                program.setFile('source/main.bs', `
+                    sub main()
+                    end sub
+
+                    sub appOnly()
+                    end sub
+                `);
+
+                const codeA = await getTranspiled('source/libA.bs');
+                const codeB = await getTranspiled('source/libB.bs');
+                const mainCode = await getTranspiled('source/main.bs');
+
+                expect(codeA).to.include('sub fromA()');
+                expect(codeB).to.include('sub fromB()');
+                expect(mainCode).not.to.include('sub appOnly()');
+            });
+        });
+
+        describe('empty keep list', () => {
+            it('still tree shakes normally when keep is an empty array', async () => {
+                program = new Program({
+                    rootDir: rootDir, stagingDir: stagingDir,
+                    treeShaking: { keep: [] }
+                });
+                program.setFile('source/main.bs', `
+                    sub main()
+                    end sub
+
+                    sub unused()
+                        print "should still be removed"
+                    end sub
+                `);
+
+                const code = await getTranspiled('source/main.bs');
+                expect(code).not.to.include('sub unused()');
+            });
+        });
+
         describe('invalid rule validation', () => {
             it('silently ignores object rules with no recognized fields', async () => {
                 // An empty object has no src/dest/functions/matches — should be skipped

From adf11e7221a9bf965ab9660117bf6d9c7116fe44 Mon Sep 17 00:00:00 2001
From: Tyler Smith <tyler@tksssoftware.com>
Date: Wed, 18 Mar 2026 10:51:07 -0300
Subject: [PATCH 05/44] Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
---
 src/util.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/util.ts b/src/util.ts
index ba42cf2c5..eee226b0b 100644
--- a/src/util.ts
+++ b/src/util.ts
@@ -420,7 +420,7 @@ export class Util {
      * - Object rules that contain none of the known fields are silently skipped.
      */
     private normalizeTreeShakingConfig(config?: TreeShakingConfig): NormalizedTreeShakingConfig {
-        const enabled = config?.enabled !== false;
+        const enabled = config?.enabled === true;
         const keep: NormalizedKeepRule[] = [];
 
         for (const entry of (config?.keep ?? []) as TreeShakingKeepEntry[]) {

From b6aed2e4514530434434f4064738be5bfe9865ae Mon Sep 17 00:00:00 2001
From: Tyler Smith <tyler@tksssoftware.com>
Date: Wed, 18 Mar 2026 10:51:32 -0300
Subject: [PATCH 06/44] Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
---
 src/bscPlugin/treeShaker/TreeShaker.ts | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/src/bscPlugin/treeShaker/TreeShaker.ts b/src/bscPlugin/treeShaker/TreeShaker.ts
index cf803c819..576f775d7 100644
--- a/src/bscPlugin/treeShaker/TreeShaker.ts
+++ b/src/bscPlugin/treeShaker/TreeShaker.ts
@@ -325,12 +325,13 @@ export class TreeShaker {
 
         // src: glob against source file path (relative patterns resolved from rootDir)
         if (rule.src) {
-            const srcPath = file.srcPath;
+            const srcPath = util.standardizePath(file.srcPath);
             const matched = rule.src.some(pattern => {
                 const resolved = path.isAbsolute(pattern)
                     ? pattern
-                    : `${this.rootDir}/${pattern}`;
-                return minimatch(srcPath, resolved, { nocase: true });
+                    : path.resolve(this.rootDir, pattern);
+                const normalizedResolved = util.standardizePath(resolved);
+                return minimatch(srcPath, normalizedResolved, { nocase: true });
             });
             if (!matched) {
                 return false;

From 5d18b910a60dbf6d15e1578db101d06aacd33b51 Mon Sep 17 00:00:00 2001
From: Tyler Smith <tyler@tksssoftware.com>
Date: Wed, 18 Mar 2026 11:11:58 -0300
Subject: [PATCH 07/44] correct tests

---
 src/bscPlugin/treeShaker/TreeShaker.spec.ts | 53 ++++++++++++++-------
 1 file changed, 36 insertions(+), 17 deletions(-)

diff --git a/src/bscPlugin/treeShaker/TreeShaker.spec.ts b/src/bscPlugin/treeShaker/TreeShaker.spec.ts
index e70476d93..f4f2e45f7 100644
--- a/src/bscPlugin/treeShaker/TreeShaker.spec.ts
+++ b/src/bscPlugin/treeShaker/TreeShaker.spec.ts
@@ -4,7 +4,7 @@ import { standardizePath as s } from '../../util';
 import * as fsExtra from 'fs-extra';
 import undent from 'undent';
 
-describe('TreeShakerValidator', () => {
+describe.only('TreeShakerValidator', () => {
     let program: Program;
     const tempDir = s`${__dirname}/../.tmp`;
     const rootDir = s`${tempDir}/rootDir`;
@@ -14,7 +14,7 @@ describe('TreeShakerValidator', () => {
         fsExtra.emptyDirSync(rootDir);
         fsExtra.emptyDirSync(stagingDir);
 
-        program = new Program({ rootDir: rootDir, stagingDir: stagingDir });
+        program = new Program({ rootDir: rootDir, stagingDir: stagingDir, treeShaking: { enabled: true } });
     });
 
     afterEach(() => {
@@ -436,14 +436,14 @@ describe('TreeShakerValidator', () => {
             expect(code).to.include('sub calledFromDead()');
         });
 
-        it('can be disabled via treeShaking.enabled = false', async () => {
-            program = new Program({ rootDir: rootDir, stagingDir: stagingDir, treeShaking: { enabled: false } });
+        it('is disabled by default — unused functions are preserved when treeShaking is not configured', async () => {
+            program = new Program({ rootDir: rootDir, stagingDir: stagingDir });
             program.setFile('source/main.bs', `
                 sub main()
                 end sub
 
                 sub unused()
-                    print "I should survive"
+                    print "I should survive when tree shaking is off"
                 end sub
             `);
 
@@ -451,6 +451,22 @@ describe('TreeShakerValidator', () => {
             expect(code).to.include('sub main()');
             expect(code).to.include('sub unused()');
         });
+
+        it('must be explicitly enabled via treeShaking.enabled = true', async () => {
+            program = new Program({ rootDir: rootDir, stagingDir: stagingDir, treeShaking: { enabled: true } });
+            program.setFile('source/main.bs', `
+                sub main()
+                end sub
+
+                sub unused()
+                    print "I should be removed when tree shaking is on"
+                end sub
+            `);
+
+            const code = await getTranspiled('source/main.bs');
+            expect(code).to.include('sub main()');
+            expect(code).not.to.include('sub unused()');
+        });
     });
 
     describe('XML interface functions', () => {
@@ -514,7 +530,7 @@ describe('TreeShakerValidator', () => {
             it('keeps a function matched by exact BrightScript name', async () => {
                 program = new Program({
                     rootDir: rootDir, stagingDir: stagingDir,
-                    treeShaking: { keep: ['unusedHelper'] }
+                    treeShaking: { enabled: true, keep: ['unusedHelper'] }
                 });
                 program.setFile('source/main.bs', `
                     sub main()
@@ -537,7 +553,7 @@ describe('TreeShakerValidator', () => {
             it('keeps a namespaced function matched by BrightScript transpiled name', async () => {
                 program = new Program({
                     rootDir: rootDir, stagingDir: stagingDir,
-                    treeShaking: { keep: ['utils_helper'] }
+                    treeShaking: { enabled: true, keep: ['utils_helper'] }
                 });
                 program.setFile('source/main.bs', `
                     namespace utils
@@ -564,7 +580,7 @@ describe('TreeShakerValidator', () => {
             it('keeps functions matched by exact name in functions array', async () => {
                 program = new Program({
                     rootDir: rootDir, stagingDir: stagingDir,
-                    treeShaking: { keep: [{ functions: ['keepMe', 'alsoKeepMe'] }] }
+                    treeShaking: { enabled: true, keep: [{ functions: ['keepMe', 'alsoKeepMe'] }] }
                 });
                 program.setFile('source/main.bs', `
                     sub main()
@@ -592,7 +608,7 @@ describe('TreeShakerValidator', () => {
             it('is case-insensitive for function names', async () => {
                 program = new Program({
                     rootDir: rootDir, stagingDir: stagingDir,
-                    treeShaking: { keep: [{ functions: ['UnusedHelper'] }] }
+                    treeShaking: { enabled: true, keep: [{ functions: ['UnusedHelper'] }] }
                 });
                 program.setFile('source/main.bs', `
                     sub main()
@@ -612,7 +628,7 @@ describe('TreeShakerValidator', () => {
             it('keeps functions matching a wildcard pattern', async () => {
                 program = new Program({
                     rootDir: rootDir, stagingDir: stagingDir,
-                    treeShaking: { keep: [{ matches: ['rodash_*'] }] }
+                    treeShaking: { enabled: true, keep: [{ matches: ['rodash_*'] }] }
                 });
                 program.setFile('source/main.bs', `
                     sub main()
@@ -642,7 +658,7 @@ describe('TreeShakerValidator', () => {
             it('keeps all functions in files matching the src glob', async () => {
                 program = new Program({
                     rootDir: rootDir, stagingDir: stagingDir,
-                    treeShaking: { keep: [{ src: 'source/vendor/**/*' }] }
+                    treeShaking: { enabled: true, keep: [{ src: 'source/vendor/**/*' }] }
                 });
                 program.setFile('source/vendor/lib.bs', `
                     sub vendorHelper()
@@ -675,7 +691,7 @@ describe('TreeShakerValidator', () => {
             it('keeps all functions in files matching the dest pkg path', async () => {
                 program = new Program({
                     rootDir: rootDir, stagingDir: stagingDir,
-                    treeShaking: { keep: [{ dest: 'source/vendor/**/*' }] }
+                    treeShaking: { enabled: true, keep: [{ dest: 'source/vendor/**/*' }] }
                 });
                 program.setFile('source/vendor/lib.bs', `
                     sub vendorHelper()
@@ -704,6 +720,7 @@ describe('TreeShakerValidator', () => {
                 program = new Program({
                     rootDir: rootDir, stagingDir: stagingDir,
                     treeShaking: {
+                        enabled: true,
                         keep: [{ src: 'source/lib.bs', functions: ['specialFn'] }]
                     }
                 });
@@ -741,6 +758,7 @@ describe('TreeShakerValidator', () => {
                 program = new Program({
                     rootDir: rootDir, stagingDir: stagingDir,
                     treeShaking: {
+                        enabled: true,
                         keep: [
                             { functions: ['keepByName'] },
                             { matches: ['keepBy*'] }
@@ -776,6 +794,7 @@ describe('TreeShakerValidator', () => {
                 program = new Program({
                     rootDir: rootDir, stagingDir: stagingDir,
                     treeShaking: {
+                        enabled: true,
                         keep: [{ src: 'source/lib.bs', functions: ['sharedName'] }]
                     }
                 });
@@ -806,7 +825,7 @@ describe('TreeShakerValidator', () => {
             it('preserves transitive callees of a kept function', async () => {
                 program = new Program({
                     rootDir: rootDir, stagingDir: stagingDir,
-                    treeShaking: { keep: ['topLevel'] }
+                    treeShaking: { enabled: true, keep: ['topLevel'] }
                 });
                 program.setFile('source/main.bs', `
                     sub main()
@@ -836,7 +855,7 @@ describe('TreeShakerValidator', () => {
             it('keeps functions matching any pattern in the matches array', async () => {
                 program = new Program({
                     rootDir: rootDir, stagingDir: stagingDir,
-                    treeShaking: { keep: [{ matches: ['foo_*', 'bar_*'] }] }
+                    treeShaking: { enabled: true, keep: [{ matches: ['foo_*', 'bar_*'] }] }
                 });
                 program.setFile('source/main.bs', `
                     sub main()
@@ -866,7 +885,7 @@ describe('TreeShakerValidator', () => {
             it('keeps functions from any matching source path', async () => {
                 program = new Program({
                     rootDir: rootDir, stagingDir: stagingDir,
-                    treeShaking: { keep: [{ src: ['source/libA.bs', 'source/libB.bs'] }] }
+                    treeShaking: { enabled: true, keep: [{ src: ['source/libA.bs', 'source/libB.bs'] }] }
                 });
                 program.setFile('source/libA.bs', `
                     sub fromA()
@@ -898,7 +917,7 @@ describe('TreeShakerValidator', () => {
             it('still tree shakes normally when keep is an empty array', async () => {
                 program = new Program({
                     rootDir: rootDir, stagingDir: stagingDir,
-                    treeShaking: { keep: [] }
+                    treeShaking: { enabled: true, keep: [] }
                 });
                 program.setFile('source/main.bs', `
                     sub main()
@@ -919,7 +938,7 @@ describe('TreeShakerValidator', () => {
                 // An empty object has no src/dest/functions/matches — should be skipped
                 program = new Program({
                     rootDir: rootDir, stagingDir: stagingDir,
-                    treeShaking: { keep: [{} as any] }
+                    treeShaking: { enabled: true, keep: [{} as any] }
                 });
                 program.setFile('source/main.bs', `
                     sub main()

From 208d9d6dd4d98f90dd5b58a3d84bdbdb474f2ee3 Mon Sep 17 00:00:00 2001
From: Tyler Smith <tyler@tksssoftware.com>
Date: Wed, 18 Mar 2026 11:16:03 -0300
Subject: [PATCH 08/44] remove only

---
 src/bscPlugin/treeShaker/TreeShaker.spec.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/bscPlugin/treeShaker/TreeShaker.spec.ts b/src/bscPlugin/treeShaker/TreeShaker.spec.ts
index f4f2e45f7..603d9f59d 100644
--- a/src/bscPlugin/treeShaker/TreeShaker.spec.ts
+++ b/src/bscPlugin/treeShaker/TreeShaker.spec.ts
@@ -4,7 +4,7 @@ import { standardizePath as s } from '../../util';
 import * as fsExtra from 'fs-extra';
 import undent from 'undent';
 
-describe.only('TreeShakerValidator', () => {
+describe('TreeShakerValidator', () => {
     let program: Program;
     const tempDir = s`${__dirname}/../.tmp`;
     const rootDir = s`${tempDir}/rootDir`;

From e690a39d0ac236f9e7fd189377142fddd8a43445 Mon Sep 17 00:00:00 2001
From: Tyler Smith <tyler@tksssoftware.com>
Date: Wed, 18 Mar 2026 11:31:32 -0300
Subject: [PATCH 09/44] bsconfig.schema.json update

---
 bsconfig.schema.json                   | 60 ++++++++++++++++++++++++++
 src/BsConfig.ts                        |  2 +-
 src/bscPlugin/treeShaker/TreeShaker.ts | 32 ++++++--------
 src/files/BrsFile.ts                   |  4 +-
 src/util.ts                            |  3 +-
 5 files changed, 79 insertions(+), 22 deletions(-)

diff --git a/bsconfig.schema.json b/bsconfig.schema.json
index 9dd7a7db7..4e75cfdb1 100644
--- a/bsconfig.schema.json
+++ b/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" } }
+                                        ]
+                                    }
+                                }
+                            }
+                        ]
+                    }
+                }
+            }
         }
     }
 }
diff --git a/src/BsConfig.ts b/src/BsConfig.ts
index 4ca44f679..66cdf3df4 100644
--- a/src/BsConfig.ts
+++ b/src/BsConfig.ts
@@ -243,7 +243,7 @@ export interface TreeShakingKeepRule {
 
 export interface TreeShakingConfig {
     /**
-     * Enable or disable tree shaking. Defaults to `true`.
+     * Enable or disable tree shaking. Defaults to `false` (opt-in).
      */
     enabled?: boolean;
     /**
diff --git a/src/bscPlugin/treeShaker/TreeShaker.ts b/src/bscPlugin/treeShaker/TreeShaker.ts
index 576f775d7..16c7eb055 100644
--- a/src/bscPlugin/treeShaker/TreeShaker.ts
+++ b/src/bscPlugin/treeShaker/TreeShaker.ts
@@ -120,29 +120,25 @@ export class TreeShaker {
         //   • prevFunctionEndLine < N <= F.startLine  (comment in the header region above F)
         collected.sort((a, b) => a.stmt.range.start.line - b.stmt.range.start.line);
 
+        // Sort keep-flag lines once so we can advance a pointer linearly O(functions + keepLines).
+        const keepLines = [...file.keepFlagLines].sort((a, b) => a - b);
+        let keepIdx = 0;
+
         let prevEndLine = -1;
         for (const { bsName, stmt } of collected) {
             const startLine = stmt.range.start.line;
-            if (this.hasBsKeepInRegion(file, prevEndLine, startLine)) {
+            // Skip any keep lines that fall before or inside the previous function.
+            while (keepIdx < keepLines.length && keepLines[keepIdx] <= prevEndLine) {
+                keepIdx++;
+            }
+            // If the next keep line is within (prevEndLine, startLine], this function is kept.
+            if (keepIdx < keepLines.length && keepLines[keepIdx] <= startLine) {
                 this.keepCommented.add(bsName);
             }
             prevEndLine = stmt.range.end.line;
         }
     }
 
-    /**
-     * Returns true if any `bs:keep` comment line falls in the half-open interval
-     * (prevEndLine, functionStartLine] — i.e., in the "header region" above a function.
-     */
-    private hasBsKeepInRegion(file: BrsFile, prevEndLine: number, functionStartLine: number): boolean {
-        for (const line of file.keepFlagLines) {
-            if (line > prevEndLine && line <= functionStartLine) {
-                return true;
-            }
-        }
-        return false;
-    }
-
     private collectXmlFile(file: XmlFile) {
         const component = file.parser.ast.component as any;
 
@@ -338,11 +334,11 @@ export class TreeShaker {
             }
         }
 
-        // dest: glob against package-relative destination path (pkgPath)
+        // dest: glob against package-relative destination path (pkgPath).
+        // Normalize to forward slashes so patterns written with `/` work on Windows.
         if (rule.dest) {
-            const pkgPath = file.pkgPath;
-            const matched = rule.dest.some(pattern => minimatch(pkgPath, pattern, { nocase: true })
-            );
+            const pkgPath = file.pkgPath.replace(/\\/g, '/');
+            const matched = rule.dest.some(pattern => minimatch(pkgPath, pattern.replace(/\\/g, '/'), { nocase: true }));
             if (!matched) {
                 return false;
             }
diff --git a/src/files/BrsFile.ts b/src/files/BrsFile.ts
index 41384f8bf..897f01aec 100644
--- a/src/files/BrsFile.ts
+++ b/src/files/BrsFile.ts
@@ -1471,7 +1471,7 @@ export const KeywordCompletions = Object.keys(Keywords)
  * Handles both `'` and `rem` starters, with optional leading whitespace.
  */
 function isBsKeepComment(text: string): boolean {
-    // Strip the comment starter (`'` or `rem`) then check for `bs:keep`
-    const lower = text.toLowerCase().replace(/^(?:rem|')/, '').trimLeft();
+    // Strip optional leading whitespace and the comment starter (`'` or `rem`), then check for `bs:keep`
+    const lower = text.toLowerCase().trimLeft().replace(/^(?:rem|')/, '').trimLeft();
     return lower.startsWith('bs:keep');
 }
diff --git a/src/util.ts b/src/util.ts
index eee226b0b..33c4a35e0 100644
--- a/src/util.ts
+++ b/src/util.ts
@@ -423,7 +423,8 @@ export class Util {
         const enabled = config?.enabled === true;
         const keep: NormalizedKeepRule[] = [];
 
-        for (const entry of (config?.keep ?? []) as TreeShakingKeepEntry[]) {
+        const keepEntries = Array.isArray(config?.keep) ? config.keep : [];
+        for (const entry of keepEntries as TreeShakingKeepEntry[]) {
             if (typeof entry === 'string') {
                 keep.push({ functions: [entry.toLowerCase()] });
             } else if (entry && typeof entry === 'object') {

From 0d70977863cedb62eda6b3144197b9c0aba0ad46 Mon Sep 17 00:00:00 2001
From: Tyler Smith <tyler@tksssoftware.com>
Date: Wed, 18 Mar 2026 14:02:32 -0300
Subject: [PATCH 10/44] readme updates

---
 docs/readme.md  |  15 ++++
 docs/shaking.md | 224 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 239 insertions(+)
 create mode 100644 docs/shaking.md

diff --git a/docs/readme.md b/docs/readme.md
index 6bb8e9961..60f19a0e0 100644
--- a/docs/readme.md
+++ b/docs/readme.md
@@ -108,3 +108,18 @@ second line text`
 ```brighterscript
 authStatus = user <> invalid ? "logged in" : "not logged in"
 ```
+
+## [Tree Shaking](shaking.md)
+Tree shaking removes unused functions from your transpiled output. Opt in via `bsconfig.json`, then use `' bs:keep` to protect functions the static analysis can't see.
+```json
+{
+    "treeShaking": {
+        "enabled": true
+    }
+}
+```
+```brightscript
+sub onDynamicCallback() ' bs:keep
+    ' won't be removed even with no visible callers
+end sub
+```
diff --git a/docs/shaking.md b/docs/shaking.md
new file mode 100644
index 000000000..0f8e8966a
--- /dev/null
+++ b/docs/shaking.md
@@ -0,0 +1,224 @@
+# Tree Shaking
+
+Tree shaking is BrighterScript's dead code elimination feature. When enabled, any function that is never called — directly or indirectly — is removed from the transpiled output, reducing the size of your deployed channel.
+
+Tree shaking is **disabled by default**. You must explicitly opt in.
+
+## Enabling Tree Shaking
+
+Add a `treeShaking` section to your `bsconfig.json`:
+
+```json
+{
+    "treeShaking": {
+        "enabled": true
+    }
+}
+```
+
+That's the minimal configuration. With only `enabled: true`, any function that cannot be reached from a known entry point will be removed.
+
+## How It Works
+
+BrighterScript performs a two-pass analysis across the entire program before transpiling:
+
+**Pass 1 — collect definitions.** Every `sub` and `function` statement in every `.bs`/`.brs` file is recorded, along with its source file and its transpiled (BrightScript) name. `bs:keep` comments are also detected in this pass (see below). Functions declared in XML `<interface>` elements and `onChange` callbacks are collected from `.xml` component files.
+
+**Pass 2 — collect references.** The AST of every file is walked to find:
+- Direct call expressions (`doSomething()`, `myNamespace.helper()`)
+- String literals that look like identifiers — conservatively retained to support dynamic dispatch patterns like `observeField("field", "onMyFieldChanged")` and `callFunc`
+- Variable expressions that reference a known function name (function-by-reference patterns such as `m.observe(node, "field", onContentChanged)`)
+- `@.` callFunc shorthand expressions
+
+After both passes, any function that has no references and is not a protected entry point is removed from the transpiled output by replacing its statement with an empty node.
+
+### Protected Entry Points
+
+The following Roku framework callbacks are **always kept** regardless of whether they appear in any call expression:
+
+| Name | Context |
+|---|---|
+| `main` | Channel entry point |
+| `init` | SceneGraph component lifecycle |
+| `onKeyEvent` | Remote key handling |
+| `onMessage` | Task/port message handling |
+| `runUserInterface` | UI task entry point |
+| `runTask` | Background task entry point |
+
+## `bs:keep` Comments
+
+A `bs:keep` comment tells the tree shaker to unconditionally keep a specific function, even if it has no detectable callers. This is useful for functions that are invoked dynamically at runtime in ways the static analysis cannot see.
+
+### Same-Line
+
+Place the comment on the same line as the `sub` or `function` keyword:
+
+```brightscript
+sub onMyDynamicCallback() ' bs:keep
+    ' ...
+end sub
+```
+
+### Above the Function
+
+Place the comment anywhere between the end of the previous function and the start of the next one:
+
+```brightscript
+end sub
+
+' bs:keep
+sub onMyDynamicCallback()
+    ' ...
+end sub
+```
+
+Multiple lines of other comments or blank lines between `bs:keep` and the function are fine — the comment applies to the next function that follows it.
+
+### First Function in a File
+
+For the very first function in a file, `bs:keep` can appear anywhere before it (since there is no previous function to bound the region):
+
+```brightscript
+' This file's public API — prevent tree shaking
+' bs:keep
+sub publicEntry()
+    ' ...
+end sub
+```
+
+### `rem` Syntax
+
+Both `'` and `rem` comment starters are supported:
+
+```brightscript
+rem bs:keep
+sub legacyEntryPoint()
+    ' ...
+end sub
+```
+
+### What `bs:keep` Does NOT Do
+
+- A `bs:keep` comment placed **inside** a function body does not protect that function.
+- A `bs:keep` comment does not automatically keep the functions that the annotated function calls — only the annotated function itself. If those callees are also unused by the rest of the program, they will still be removed. Use [`treeShaking.keep`](#treeshakingkeep-rules) rules with dependency closure, or annotate each callee individually, if you need to retain an entire call graph.
+
+## `treeShaking.keep` Rules
+
+For coarser-grained control — keeping entire files, namespaces, or pattern-matched sets of functions — use the `keep` array in `bsconfig.json`. Each entry is either a plain string (exact function name) or a rule object.
+
+### Plain String
+
+A plain string matches the exact transpiled (BrightScript) function name, case-insensitively:
+
+```json
+{
+    "treeShaking": {
+        "enabled": true,
+        "keep": [
+            "myPublicFunction",
+            "myNamespace_helperFunction"
+        ]
+    }
+}
+```
+
+For namespaced BrighterScript functions, use the transpiled underscore form. For example, `namespace myNamespace` + `function helperFunction()` transpiles to `myNamespace_helperFunction`.
+
+### Rule Objects
+
+A rule object can filter by any combination of `functions`, `matches`, `src`, and `dest`. All fields present in a single rule must match simultaneously (AND semantics). Rules in the array are evaluated independently and a function is kept if **any** rule matches (OR semantics).
+
+#### `functions` — exact name list
+
+```json
+{
+    "keep": [
+        { "functions": "myNamespace_init" },
+        { "functions": ["analyticsTrack", "analyticsFlush"] }
+    ]
+}
+```
+
+#### `matches` — glob/wildcard against the function name
+
+```json
+{
+    "keep": [
+        { "matches": "analytics_*" },
+        { "matches": ["debug_*", "test_*"] }
+    ]
+}
+```
+
+#### `src` — glob against the source file path
+
+The pattern is resolved relative to `rootDir` unless it is an absolute path.
+
+```json
+{
+    "keep": [
+        { "src": "source/public/**/*.bs" },
+        { "src": ["source/api.bs", "source/auth.bs"] }
+    ]
+}
+```
+
+#### `dest` — glob against the package-relative destination path
+
+This matches the path the file will have inside the deployed zip (e.g. `pkg:/source/utils.brs`).
+
+```json
+{
+    "keep": [
+        { "dest": "source/public/**/*.brs" }
+    ]
+}
+```
+
+#### Combining Fields (AND within a rule)
+
+Keep only functions whose name starts with `api_` **and** that live in a specific file:
+
+```json
+{
+    "keep": [
+        {
+            "src": "source/api.bs",
+            "matches": "api_*"
+        }
+    ]
+}
+```
+
+### Dependency Closure
+
+Keep rules do not automatically pull in the transitive dependencies of a matched function. If `api_login` calls `crypto_hash` and only `api_login` is matched by a keep rule, `crypto_hash` will still be removed if nothing else calls it.
+
+To retain the entire reachable graph of a kept function, either:
+- Add a `bs:keep` comment to each function you want to preserve, or
+- Add additional keep rules (e.g. a `src` rule that covers the whole file containing the helpers)
+
+## Configuration Reference
+
+```json
+{
+    "treeShaking": {
+        "enabled": false,
+        "keep": []
+    }
+}
+```
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `enabled` | `boolean` | `false` | Must be `true` to activate tree shaking |
+| `keep` | `(string \| KeepRule)[]` | `[]` | Functions matching any entry are always retained |
+
+**KeepRule fields** (all optional; at least one required):
+
+| Field | Type | Description |
+|---|---|---|
+| `functions` | `string \| string[]` | Exact transpiled function name(s), case-insensitive |
+| `matches` | `string \| string[]` | Glob pattern(s) matched against the transpiled function name |
+| `src` | `string \| string[]` | Glob pattern(s) matched against the source file path |
+| `dest` | `string \| string[]` | Glob pattern(s) matched against the package-relative destination path |

From b00125858f4734787db95e3e7bb61b9aaa31417c Mon Sep 17 00:00:00 2001
From: Tyler Smith <tyler@tksssoftware.com>
Date: Wed, 18 Mar 2026 14:10:32 -0300
Subject: [PATCH 11/44] spec rename

---
 src/bscPlugin/treeShaker/TreeShaker.spec.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/bscPlugin/treeShaker/TreeShaker.spec.ts b/src/bscPlugin/treeShaker/TreeShaker.spec.ts
index 603d9f59d..abf965986 100644
--- a/src/bscPlugin/treeShaker/TreeShaker.spec.ts
+++ b/src/bscPlugin/treeShaker/TreeShaker.spec.ts
@@ -4,7 +4,7 @@ import { standardizePath as s } from '../../util';
 import * as fsExtra from 'fs-extra';
 import undent from 'undent';
 
-describe('TreeShakerValidator', () => {
+describe('TreeShaker', () => {
     let program: Program;
     const tempDir = s`${__dirname}/../.tmp`;
     const rootDir = s`${tempDir}/rootDir`;

From e226ecde12d1663ed2bfed90be1a523767892bcc Mon Sep 17 00:00:00 2001
From: Tyler Smith <tyler@tksssoftware.com>
Date: Wed, 18 Mar 2026 15:10:39 -0300
Subject: [PATCH 12/44] documentation fix

---
 docs/shaking.md                             | 11 ++-
 src/bscPlugin/treeShaker/TreeShaker.spec.ts | 87 +++++++++++++++++++++
 2 files changed, 92 insertions(+), 6 deletions(-)

diff --git a/docs/shaking.md b/docs/shaking.md
index 0f8e8966a..d4bffa2e4 100644
--- a/docs/shaking.md
+++ b/docs/shaking.md
@@ -100,7 +100,10 @@ end sub
 ### What `bs:keep` Does NOT Do
 
 - A `bs:keep` comment placed **inside** a function body does not protect that function.
-- A `bs:keep` comment does not automatically keep the functions that the annotated function calls — only the annotated function itself. If those callees are also unused by the rest of the program, they will still be removed. Use [`treeShaking.keep`](#treeshakingkeep-rules) rules with dependency closure, or annotate each callee individually, if you need to retain an entire call graph.
+
+### Dependency Closure
+
+A `bs:keep` annotation preserves the full call chain of the annotated function. BrighterScript's reference pass walks every function body — including those of kept functions — so anything called directly or transitively from a `bs:keep` function is automatically retained.
 
 ## `treeShaking.keep` Rules
 
@@ -192,11 +195,7 @@ Keep only functions whose name starts with `api_` **and** that live in a specifi
 
 ### Dependency Closure
 
-Keep rules do not automatically pull in the transitive dependencies of a matched function. If `api_login` calls `crypto_hash` and only `api_login` is matched by a keep rule, `crypto_hash` will still be removed if nothing else calls it.
-
-To retain the entire reachable graph of a kept function, either:
-- Add a `bs:keep` comment to each function you want to preserve, or
-- Add additional keep rules (e.g. a `src` rule that covers the whole file containing the helpers)
+Keep rules preserve the full call chain of every matched function. BrighterScript's reference pass walks every function body, so anything called directly or transitively from a kept function is automatically retained.
 
 ## Configuration Reference
 
diff --git a/src/bscPlugin/treeShaker/TreeShaker.spec.ts b/src/bscPlugin/treeShaker/TreeShaker.spec.ts
index abf965986..a9e70f981 100644
--- a/src/bscPlugin/treeShaker/TreeShaker.spec.ts
+++ b/src/bscPlugin/treeShaker/TreeShaker.spec.ts
@@ -228,6 +228,36 @@ describe('TreeShaker', () => {
             expect(code).not.to.include('sub canGo()');
         });
 
+        it('preserves the full call chain of a bs:keep function', async () => {
+            program.setFile('source/main.bs', `
+                sub main()
+                end sub
+
+                ' bs:keep
+                sub topLevel()
+                    middle()
+                end sub
+
+                sub middle()
+                    leaf()
+                end sub
+
+                sub leaf()
+                    print "end of chain"
+                end sub
+
+                sub unrelated()
+                    print "no connection to topLevel"
+                end sub
+            `);
+
+            const code = await getTranspiled('source/main.bs');
+            expect(code).to.include('sub topLevel()');
+            expect(code).to.include('sub middle()');
+            expect(code).to.include('sub leaf()');
+            expect(code).not.to.include('sub unrelated()');
+        });
+
         it('does not apply a bs:keep comment to the function before it', async () => {
             program.setFile('source/main.bs', `
                 sub main()
@@ -304,6 +334,63 @@ describe('TreeShaker', () => {
             expect(code).not.to.include('sub unused()');
         });
 
+        it('preserves a namespaced function called relatively (without namespace prefix) from within the same namespace', async () => {
+            program.setFile('source/main.bs', `
+                namespace utils
+                    sub caller()
+                        helper() ' relative call — no "utils." prefix
+                    end sub
+
+                    sub helper()
+                        print "called relatively from within the namespace"
+                    end sub
+                end namespace
+
+                sub main()
+                    utils.caller()
+                end sub
+            `);
+
+            const code = await getTranspiled('source/main.bs');
+            expect(code).to.include('utils_caller');
+            expect(code).to.include('utils_helper');
+        });
+
+        it('conservatively preserves all same-named functions across namespaces when one is called relatively', async () => {
+            // When `helper()` is called relatively inside `ns1`, the AST contains only
+            // the simple name "helper". The shaker adds "helper" to calledNames, which
+            // causes ns2_helper to survive even though it was never actually called.
+            // This is safe (no false removals) but not maximally precise.
+            program.setFile('source/main.bs', `
+                namespace ns1
+                    sub caller()
+                        helper() ' relative call — resolves to ns1_helper at runtime
+                    end sub
+
+                    sub helper()
+                        print "ns1 helper"
+                    end sub
+                end namespace
+
+                namespace ns2
+                    sub helper()
+                        print "ns2 helper — conservatively kept due to simple name match"
+                    end sub
+                end namespace
+
+                sub main()
+                    ns1.caller()
+                end sub
+            `);
+
+            const code = await getTranspiled('source/main.bs');
+            expect(code).to.include('ns1_caller');
+            expect(code).to.include('ns1_helper');
+            // ns2_helper is kept as a conservative side-effect of the simple name "helper"
+            // being in calledNames — not a bug, just imprecision in the static analysis.
+            expect(code).to.include('ns2_helper');
+        });
+
         it('preserves namespaced functions that are called', async () => {
             program.setFile('source/main.bs', `
                 namespace utils

From c58c81257409750b91f8992c80895da112bb2917 Mon Sep 17 00:00:00 2001
From: Tyler Smith <tyler@tksssoftware.com>
Date: Wed, 18 Mar 2026 15:13:05 -0300
Subject: [PATCH 13/44] runscreensaver

---
 src/bscPlugin/treeShaker/TreeShaker.ts | 1 +
 1 file changed, 1 insertion(+)

diff --git a/src/bscPlugin/treeShaker/TreeShaker.ts b/src/bscPlugin/treeShaker/TreeShaker.ts
index 16c7eb055..6769f35a2 100644
--- a/src/bscPlugin/treeShaker/TreeShaker.ts
+++ b/src/bscPlugin/treeShaker/TreeShaker.ts
@@ -25,6 +25,7 @@ export class TreeShaker {
         'onkeyevent',
         'onmessage',
         'runuserinterface',
+        'runscreensaver',
         'runtask'
     ]);
 

From 7ee562493ea1c24ae0b1a8a0d9120a4a1b4012c3 Mon Sep 17 00:00:00 2001
From: Tyler Smith <tyler@tksssoftware.com>
Date: Wed, 18 Mar 2026 15:25:51 -0300
Subject: [PATCH 14/44] optimizations

---
 src/bscPlugin/treeShaker/TreeShaker.ts | 196 ++++++++++++++++++-------
 1 file changed, 144 insertions(+), 52 deletions(-)

diff --git a/src/bscPlugin/treeShaker/TreeShaker.ts b/src/bscPlugin/treeShaker/TreeShaker.ts
index 6769f35a2..dbc4da176 100644
--- a/src/bscPlugin/treeShaker/TreeShaker.ts
+++ b/src/bscPlugin/treeShaker/TreeShaker.ts
@@ -14,6 +14,21 @@ import type { FunctionStatement } from '../../parser/Statement';
 import type { Program } from '../../Program';
 import util from '../../util';
 
+/**
+ * Keep rule with patterns pre-compiled and src paths pre-resolved.
+ * Built once per analyze() call so per-function matching is pure set/matcher lookups.
+ */
+interface CompiledRule {
+    /** Lowercased exact BrightScript names — O(1) Set lookup replaces Array.includes. */
+    functionsSet?: Set<string>;
+    /** Pre-compiled minimatch instances for `matches` glob patterns. */
+    matchesMatchers?: minimatch.Minimatch[];
+    /** Pre-compiled minimatch instances for `src` patterns, already resolved to absolute paths. */
+    srcMatchers?: minimatch.Minimatch[];
+    /** Pre-compiled minimatch instances for `dest` patterns, normalized to forward slashes. */
+    destMatchers?: minimatch.Minimatch[];
+}
+
 export class TreeShaker {
     /**
      * Roku lifecycle callbacks and framework entry points that must always be kept.
@@ -29,8 +44,16 @@ export class TreeShaker {
         'runtask'
     ]);
 
-    // Fully-qualified lowercased function names (BrighterScript style, dots) → statement + file + brsName
-    private allFunctions = new Map<string, { statement: FunctionStatement; file: BrsFile; brsName: string }>();
+    // Fully-qualified lowercased function names (BrighterScript style, dots) → brsName
+    // Used by isUnused() to resolve the BrightScript name and by the reference pass gating.
+    private allFunctions = new Map<string, string>();
+
+    // Every function statement across all files, in collection order.
+    // allFunctions stores only one entry per bsName (last write wins for name-only checks),
+    // but allStatements retains every definition so computeRemovals() can evaluate each
+    // (bsName, file) pair independently — required for correct src/dest keep-rule scoping
+    // when multiple files define a function with the same name.
+    private allStatements: Array<{ bsName: string; brsName: string; stmt: FunctionStatement; file: BrsFile }> = [];
 
     // Names referenced in CallExpression nodes (both full namespaced and simple names)
     private calledNames = new Set<string>();
@@ -44,19 +67,29 @@ export class TreeShaker {
     // Functions marked with a `bs:keep` comment — never removed regardless of references
     private keepCommented = new Set<string>();
 
-    // Normalized keep rules from config
-    private keepRules: NormalizedKeepRule[] = [];
+    // Keep rules with patterns pre-compiled — built once at the start of analyze()
+    private compiledRules: CompiledRule[] = [];
+
+    // Normalized file paths per BrsFile — computed once, reused across all rule checks for that file
+    private filePathCache = new Map<BrsFile, { srcPath: string; pkgPath: string }>();
+
+    // FunctionStatements to remove — keyed on the statement object so same-named functions
+    // in different files are tracked independently; shake() is a single Set lookup per statement
+    private toRemove = new Set<FunctionStatement>();
 
     // Resolved rootDir for src-path matching
     private rootDir = '';
 
     reset() {
         this.allFunctions.clear();
+        this.allStatements = [];
         this.calledNames.clear();
         this.stringRefs.clear();
         this.xmlInterfaceFunctions.clear();
         this.keepCommented.clear();
-        this.keepRules = [];
+        this.compiledRules = [];
+        this.filePathCache.clear();
+        this.toRemove.clear();
         this.rootDir = '';
     }
 
@@ -72,12 +105,17 @@ export class TreeShaker {
      *           by reference (e.g. sgnode.observe(node, "field", onContentChanged))
      *           is detected even when the name never appears as a string literal or
      *           direct call.
+     *
+     * After both passes, the removal set is precomputed so shake() is a single
+     * set lookup per function rather than re-running all decision logic per file.
      */
     analyze(program: Program, keepRules: NormalizedKeepRule[]) {
         this.reset();
-        this.keepRules = keepRules;
         this.rootDir = program.options.rootDir ?? process.cwd();
 
+        // Compile patterns and resolve src paths once — before any per-function work
+        this.compiledRules = this.compileRules(keepRules);
+
         // Pass 1 – definitions + XML interfaces
         for (const file of Object.values(program.files)) {
             if (isBrsFile(file)) {
@@ -93,6 +131,80 @@ export class TreeShaker {
                 this.collectReferences(file);
             }
         }
+
+        // Precompute removal decisions so shake() is O(1) per function
+        this.computeRemovals();
+    }
+
+    /**
+     * Compile NormalizedKeepRules into CompiledRules.
+     * - `functions` arrays become Sets for O(1) membership testing.
+     * - `matches`/`src`/`dest` glob strings become pre-compiled Minimatch instances.
+     * - `src` patterns are resolved to absolute paths against rootDir up front.
+     */
+    private compileRules(rules: NormalizedKeepRule[]): CompiledRule[] {
+        return rules.map(rule => {
+            const compiled: CompiledRule = {};
+
+            if (rule.functions) {
+                compiled.functionsSet = new Set(rule.functions); // already lowercased by normalizer
+            }
+
+            if (rule.matches) {
+                compiled.matchesMatchers = rule.matches.map(
+                    p => new minimatch.Minimatch(p, { nocase: true })
+                );
+            }
+
+            if (rule.src) {
+                compiled.srcMatchers = rule.src.map(pattern => {
+                    const resolved = path.isAbsolute(pattern)
+                        ? pattern
+                        : path.resolve(this.rootDir, pattern);
+                    return new minimatch.Minimatch(util.standardizePath(resolved), { nocase: true });
+                });
+            }
+
+            if (rule.dest) {
+                compiled.destMatchers = rule.dest.map(
+                    p => new minimatch.Minimatch(p.replace(/\\/g, '/'), { nocase: true })
+                );
+            }
+
+            return compiled;
+        });
+    }
+
+    /**
+     * Returns the normalized srcPath and pkgPath for a file, computing and caching
+     * them on first access so repeated rule checks for the same file pay no extra cost.
+     */
+    private getFilePaths(file: BrsFile): { srcPath: string; pkgPath: string } {
+        let cached = this.filePathCache.get(file);
+        if (!cached) {
+            cached = {
+                srcPath: util.standardizePath(file.srcPath),
+                pkgPath: file.pkgPath.replace(/\\/g, '/')
+            };
+            this.filePathCache.set(file, cached);
+        }
+        return cached;
+    }
+
+    /**
+     * After both analysis passes, iterate every collected statement and compute which
+     * should be removed.  Each (bsName, file) pair is evaluated independently so that
+     * src/dest keep rules correctly scope to the file that actually defines the function —
+     * this handles cases where multiple files define a function with the same name.
+     * Storing results keyed on the FunctionStatement object means shake() needs only a
+     * single Set lookup per statement rather than re-running all decision logic per file.
+     */
+    private computeRemovals() {
+        for (const { bsName, brsName, stmt, file } of this.allStatements) {
+            if (this.isUnused(bsName) && !this.isKept(brsName, file)) {
+                this.toRemove.add(stmt);
+            }
+        }
     }
 
     // -------------------------------------------------------------------------
@@ -109,7 +221,8 @@ export class TreeShaker {
                 const bsName = stmt.getName(ParseMode.BrighterScript)?.toLowerCase();
                 const brsName = stmt.getName(ParseMode.BrightScript)?.toLowerCase();
                 if (bsName && brsName) {
-                    this.allFunctions.set(bsName, { statement: stmt, file: file, brsName: brsName });
+                    this.allFunctions.set(bsName, brsName);
+                    this.allStatements.push({ bsName, brsName, stmt, file });
                     collected.push({ bsName: bsName, brsName: brsName, stmt: stmt });
                 }
             }
@@ -291,58 +404,41 @@ export class TreeShaker {
     }
 
     /**
-     * Returns true when the function matches any keep rule from config.
+     * Returns true when the function matches any compiled keep rule from config.
      * Rule fields are ANDed; rules across the list are ORed.
      */
-    isKept(bsName: string, brsName: string, file: BrsFile): boolean {
-        for (const rule of this.keepRules) {
-            if (this.ruleMatches(rule, brsName, file)) {
+    isKept(brsName: string, file: BrsFile): boolean {
+        if (this.compiledRules.length === 0) {
+            return false;
+        }
+        const { srcPath, pkgPath } = this.getFilePaths(file);
+        for (const rule of this.compiledRules) {
+            if (this.ruleMatches(rule, brsName, srcPath, pkgPath)) {
                 return true;
             }
         }
         return false;
     }
 
-    private ruleMatches(rule: NormalizedKeepRule, brsName: string, file: BrsFile): boolean {
-        // functions: exact name match (BrightScript/transpiled names)
-        if (rule.functions) {
-            if (!rule.functions.includes(brsName)) {
-                return false;
-            }
+    private ruleMatches(rule: CompiledRule, brsName: string, srcPath: string, pkgPath: string): boolean {
+        // functions: O(1) Set lookup
+        if (rule.functionsSet && !rule.functionsSet.has(brsName)) {
+            return false;
         }
 
-        // matches: glob/wildcard against function name
-        if (rule.matches) {
-            const matched = rule.matches.some(pattern => minimatch(brsName, pattern, { nocase: true })
-            );
-            if (!matched) {
-                return false;
-            }
+        // matches: pre-compiled glob matchers
+        if (rule.matchesMatchers && !rule.matchesMatchers.some(m => m.match(brsName))) {
+            return false;
         }
 
-        // src: glob against source file path (relative patterns resolved from rootDir)
-        if (rule.src) {
-            const srcPath = util.standardizePath(file.srcPath);
-            const matched = rule.src.some(pattern => {
-                const resolved = path.isAbsolute(pattern)
-                    ? pattern
-                    : path.resolve(this.rootDir, pattern);
-                const normalizedResolved = util.standardizePath(resolved);
-                return minimatch(srcPath, normalizedResolved, { nocase: true });
-            });
-            if (!matched) {
-                return false;
-            }
+        // src: pre-compiled matchers against already-standardized absolute path
+        if (rule.srcMatchers && !rule.srcMatchers.some(m => m.match(srcPath))) {
+            return false;
         }
 
-        // dest: glob against package-relative destination path (pkgPath).
-        // Normalize to forward slashes so patterns written with `/` work on Windows.
-        if (rule.dest) {
-            const pkgPath = file.pkgPath.replace(/\\/g, '/');
-            const matched = rule.dest.some(pattern => minimatch(pkgPath, pattern.replace(/\\/g, '/'), { nocase: true }));
-            if (!matched) {
-                return false;
-            }
+        // dest: pre-compiled matchers against already-normalized pkgPath
+        if (rule.destMatchers && !rule.destMatchers.some(m => m.match(pkgPath))) {
+            return false;
         }
 
         return true;
@@ -355,6 +451,8 @@ export class TreeShaker {
     /**
      * Walk the file and replace every unused FunctionStatement with an EmptyStatement,
      * effectively removing it from transpiled output.
+     * The removal set was precomputed in analyze(), so this is a single Set lookup
+     * per function with no rule evaluation or path normalization at shake time.
      */
     shake(file: BscFile, editor: AstEditor) {
         if (!isBrsFile(file)) {
@@ -363,13 +461,7 @@ export class TreeShaker {
 
         file.ast.walk(createVisitor({
             FunctionStatement: (stmt) => {
-                const bsName = stmt.getName(ParseMode.BrighterScript)?.toLowerCase();
-                if (!bsName) {
-                    return;
-                }
-                const entry = this.allFunctions.get(bsName);
-                const brsName = entry?.brsName ?? bsName;
-                if (this.isUnused(bsName) && !this.isKept(bsName, brsName, file)) {
+                if (this.toRemove.has(stmt)) {
                     return new EmptyStatement();
                 }
             }

From 19f13f8090b0bc148c605fda79fbbf4775768e41 Mon Sep 17 00:00:00 2001
From: Tyler Smith <tyler@tksssoftware.com>
Date: Wed, 18 Mar 2026 15:31:12 -0300
Subject: [PATCH 15/44] Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
---
 docs/shaking.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/shaking.md b/docs/shaking.md
index d4bffa2e4..215f5567c 100644
--- a/docs/shaking.md
+++ b/docs/shaking.md
@@ -1,6 +1,6 @@
 # Tree Shaking
 
-Tree shaking is BrighterScript's dead code elimination feature. When enabled, any function that is never called — directly or indirectly — is removed from the transpiled output, reducing the size of your deployed channel.
+Tree shaking is BrighterScript's dead code elimination feature. When enabled, it can remove functions that have no detectable references and aren't protected entry points, reducing the size of your deployed channel.
 
 Tree shaking is **disabled by default**. You must explicitly opt in.
 
@@ -16,7 +16,7 @@ Add a `treeShaking` section to your `bsconfig.json`:
 }
 ```
 
-That's the minimal configuration. With only `enabled: true`, any function that cannot be reached from a known entry point will be removed.
+That's the minimal configuration. With only `enabled: true`, the tree shaker removes functions that have no detectable references and are not protected entry points.
 
 ## How It Works
 

From def4082ca739fbe18bf1b796244fb78361c673f5 Mon Sep 17 00:00:00 2001
From: Tyler Smith <tyler@tksssoftware.com>
Date: Wed, 18 Mar 2026 15:37:05 -0300
Subject: [PATCH 16/44] Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
---
 src/BsConfig.ts | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/src/BsConfig.ts b/src/BsConfig.ts
index 66cdf3df4..c04609726 100644
--- a/src/BsConfig.ts
+++ b/src/BsConfig.ts
@@ -248,7 +248,9 @@ export interface TreeShakingConfig {
     enabled?: boolean;
     /**
      * Declarations matching any rule in this list are always retained,
-     * along with their full dependency closure.
+     * along with their statically detectable dependencies (as determined by static analysis).
+     * Dynamic dependencies may not be detected, and statically referenced callees may be kept
+     * even when referenced only from otherwise dead code.
      */
     keep?: TreeShakingKeepEntry[];
 }

From e5d83aa2470ad8cf525e4345b69d1c626abdda39 Mon Sep 17 00:00:00 2001
From: Tyler Smith <tyler@tksssoftware.com>
Date: Wed, 18 Mar 2026 15:52:54 -0300
Subject: [PATCH 17/44] resolve issues

---
 docs/shaking.md                             |  5 +-
 src/bscPlugin/treeShaker/TreeShaker.spec.ts | 96 ++++++++++++++++++++-
 src/bscPlugin/treeShaker/TreeShaker.ts      | 64 ++++++++++----
 3 files changed, 145 insertions(+), 20 deletions(-)

diff --git a/docs/shaking.md b/docs/shaking.md
index 215f5567c..1fadd0a3e 100644
--- a/docs/shaking.md
+++ b/docs/shaking.md
@@ -168,12 +168,13 @@ The pattern is resolved relative to `rootDir` unless it is an absolute path.
 
 #### `dest` — glob against the package-relative destination path
 
-This matches the path the file will have inside the deployed zip (e.g. `pkg:/source/utils.brs`).
+Matches the path the file will have inside the deployed zip. BrighterScript source files (`.bs`) are matched using their transpiled extension (`.brs`), so always write `.brs` in dest patterns. An optional `pkg:/` prefix is accepted and stripped before matching.
 
 ```json
 {
     "keep": [
-        { "dest": "source/public/**/*.brs" }
+        { "dest": "source/public/**/*.brs" },
+        { "dest": "pkg:/source/vendor/**/*.brs" }
     ]
 }
 ```
diff --git a/src/bscPlugin/treeShaker/TreeShaker.spec.ts b/src/bscPlugin/treeShaker/TreeShaker.spec.ts
index a9e70f981..0a6c3a302 100644
--- a/src/bscPlugin/treeShaker/TreeShaker.spec.ts
+++ b/src/bscPlugin/treeShaker/TreeShaker.spec.ts
@@ -277,6 +277,49 @@ describe('TreeShaker', () => {
             expect(code).to.include('sub mustStay()');
         });
 
+        it('preserves a namespaced function passed by reference using its relative name from within the same namespace', async () => {
+            // Inside namespace ns, `helper` is a relative reference to `ns.helper`.
+            // allFunctions only stores 'ns.helper', so the VariableExpression gate must
+            // also check allSimpleNames or it would miss the reference and remove ns.helper.
+            program.setFile('source/main.bs', `
+                namespace ns
+                    sub init()
+                        m.top.observeField("data", helper)
+                    end sub
+
+                    sub helper()
+                        print "referenced relatively by name"
+                    end sub
+                end namespace
+
+                sub main()
+                    ns.init()
+                end sub
+            `);
+
+            const code = await getTranspiled('source/main.bs');
+            expect(code).to.include('ns_helper');
+        });
+
+        it('preserves a namespaced function passed by dotted reference from outside the namespace', async () => {
+            // ns.helper appears as a DottedGetExpression, not a CallExpression.
+            // The DottedGetExpression gate must check allFunctions.has(full) correctly.
+            program.setFile('source/main.bs', `
+                namespace ns
+                    sub helper()
+                        print "referenced by dotted get"
+                    end sub
+                end namespace
+
+                sub main()
+                    m.top.observeField("data", ns.helper)
+                end sub
+            `);
+
+            const code = await getTranspiled('source/main.bs');
+            expect(code).to.include('ns_helper');
+        });
+
         it('preserves functions referenced as string literals (observeField pattern)', async () => {
             program.setFile('source/main.bs', `
                 sub init()
@@ -334,6 +377,28 @@ describe('TreeShaker', () => {
             expect(code).not.to.include('sub unused()');
         });
 
+        it('preserves a namespaced function called by its transpiled underscore name from a .brs file', async () => {
+            // A plain .brs file has no namespaces — it calls utils_helper() directly.
+            // calledNames receives "utils_helper" (underscore form), which matches neither
+            // the bsName "utils.helper" nor the simpleName "helper". isUnused must also
+            // check brsName or the function is incorrectly removed.
+            program.setFile('source/utils.bs', `
+                namespace utils
+                    sub helper()
+                        print "called from brs"
+                    end sub
+                end namespace
+            `);
+            program.setFile('source/main.brs', `
+                sub main()
+                    utils_helper()
+                end sub
+            `);
+
+            const code = await getTranspiled('source/utils.bs');
+            expect(code).to.include('utils_helper');
+        });
+
         it('preserves a namespaced function called relatively (without namespace prefix) from within the same namespace', async () => {
             program.setFile('source/main.bs', `
                 namespace utils
@@ -775,10 +840,37 @@ describe('TreeShaker', () => {
         });
 
         describe('dest rule', () => {
-            it('keeps all functions in files matching the dest pkg path', async () => {
+            it('keeps all functions in files matching the dest glob using the transpiled .brs extension', async () => {
+                // .bs source files deploy as .brs — dest patterns must use .brs to match
+                program = new Program({
+                    rootDir: rootDir, stagingDir: stagingDir,
+                    treeShaking: { enabled: true, keep: [{ dest: 'source/vendor/**/*.brs' }] }
+                });
+                program.setFile('source/vendor/lib.bs', `
+                    sub vendorHelper()
+                        print "from vendor"
+                    end sub
+                `);
+                program.setFile('source/main.bs', `
+                    sub main()
+                    end sub
+
+                    sub appHelper()
+                        print "app code - removed"
+                    end sub
+                `);
+
+                const vendorCode = await getTranspiled('source/vendor/lib.bs');
+                const mainCode = await getTranspiled('source/main.bs');
+
+                expect(vendorCode).to.include('sub vendorHelper()');
+                expect(mainCode).not.to.include('sub appHelper()');
+            });
+
+            it('accepts a pkg:/ prefix in dest patterns and strips it before matching', async () => {
                 program = new Program({
                     rootDir: rootDir, stagingDir: stagingDir,
-                    treeShaking: { enabled: true, keep: [{ dest: 'source/vendor/**/*' }] }
+                    treeShaking: { enabled: true, keep: [{ dest: 'pkg:/source/vendor/**/*.brs' }] }
                 });
                 program.setFile('source/vendor/lib.bs', `
                     sub vendorHelper()
diff --git a/src/bscPlugin/treeShaker/TreeShaker.ts b/src/bscPlugin/treeShaker/TreeShaker.ts
index dbc4da176..6dd1b20c6 100644
--- a/src/bscPlugin/treeShaker/TreeShaker.ts
+++ b/src/bscPlugin/treeShaker/TreeShaker.ts
@@ -45,9 +45,16 @@ export class TreeShaker {
     ]);
 
     // Fully-qualified lowercased function names (BrighterScript style, dots) → brsName
-    // Used by isUnused() to resolve the BrightScript name and by the reference pass gating.
     private allFunctions = new Map<string, string>();
 
+    // Simple (unqualified) names of every known function — the last dot-segment of each bsName.
+    // A separate set is needed because allFunctions is keyed by fully-qualified names, so
+    // allFunctions.has('helper') returns false for 'ns.helper'. Without this, a namespaced
+    // function passed by reference using its relative name (e.g. observeField("x", helper)
+    // from inside namespace ns) would not be detected by the VariableExpression/
+    // DottedGetExpression gates and could be incorrectly removed.
+    private allSimpleNames = new Set<string>();
+
     // Every function statement across all files, in collection order.
     // allFunctions stores only one entry per bsName (last write wins for name-only checks),
     // but allStatements retains every definition so computeRemovals() can evaluate each
@@ -82,6 +89,7 @@ export class TreeShaker {
 
     reset() {
         this.allFunctions.clear();
+        this.allSimpleNames.clear();
         this.allStatements = [];
         this.calledNames.clear();
         this.stringRefs.clear();
@@ -166,9 +174,12 @@ export class TreeShaker {
             }
 
             if (rule.dest) {
-                compiled.destMatchers = rule.dest.map(
-                    p => new minimatch.Minimatch(p.replace(/\\/g, '/'), { nocase: true })
-                );
+                compiled.destMatchers = rule.dest.map(p => {
+                    // Normalize backslashes and strip optional pkg:/ scheme prefix so
+                    // patterns like "pkg:/source/**/*.brs" and "source/**/*.brs" both work.
+                    const normalized = p.replace(/\\/g, '/').replace(/^pkg:\//i, '');
+                    return new minimatch.Minimatch(normalized, { nocase: true });
+                });
             }
 
             return compiled;
@@ -176,15 +187,21 @@ export class TreeShaker {
     }
 
     /**
-     * Returns the normalized srcPath and pkgPath for a file, computing and caching
-     * them on first access so repeated rule checks for the same file pay no extra cost.
+     * Returns the normalized srcPath and deployedPkgPath for a file, computing and
+     * caching them on first access so repeated rule checks for the same file pay no
+     * extra cost.
+     *
+     * pkgPath uses the *deployed* extension: .bs files transpile to .brs, so
+     * `source/foo.bs` becomes `source/foo.brs`.  This matches what users naturally
+     * write in dest glob patterns (e.g. `source/vendor/**\/*.brs`).
      */
     private getFilePaths(file: BrsFile): { srcPath: string; pkgPath: string } {
         let cached = this.filePathCache.get(file);
         if (!cached) {
+            const rawPkg = file.pkgPath.replace(/\\/g, '/');
             cached = {
                 srcPath: util.standardizePath(file.srcPath),
-                pkgPath: file.pkgPath.replace(/\\/g, '/')
+                pkgPath: rawPkg.replace(/\.bs$/i, '.brs')
             };
             this.filePathCache.set(file, cached);
         }
@@ -201,7 +218,7 @@ export class TreeShaker {
      */
     private computeRemovals() {
         for (const { bsName, brsName, stmt, file } of this.allStatements) {
-            if (this.isUnused(bsName) && !this.isKept(brsName, file)) {
+            if (this.isUnused(bsName, brsName) && !this.isKept(brsName, file)) {
                 this.toRemove.add(stmt);
             }
         }
@@ -222,6 +239,7 @@ export class TreeShaker {
                 const brsName = stmt.getName(ParseMode.BrightScript)?.toLowerCase();
                 if (bsName && brsName) {
                     this.allFunctions.set(bsName, brsName);
+                    this.allSimpleNames.add(bsName.split('.').pop()!);
                     this.allStatements.push({ bsName, brsName, stmt, file });
                     collected.push({ bsName: bsName, brsName: brsName, stmt: stmt });
                 }
@@ -339,10 +357,13 @@ export class TreeShaker {
                 //   sgnode.observe(node, "field", onContentChanged)
                 //   callbacks = [onFoo, onBar]
                 // where the function is passed by reference rather than called or
-                // named as a string.  We only check names that are actually defined
-                // functions to avoid bloating calledNames with every local variable.
+                // named as a string.  Gate on allSimpleNames (not allFunctions) so that
+                // namespaced functions referenced by their relative/simple name from
+                // within the same namespace are correctly detected — allFunctions only
+                // stores fully-qualified names so allFunctions.has('helper') would miss
+                // a function defined as 'ns.helper'.
                 const name = (expr as any).name?.text?.toLowerCase();
-                if (name && this.allFunctions.has(name)) {
+                if (name && (this.allFunctions.has(name) || this.allSimpleNames.has(name))) {
                     this.calledNames.add(name);
                 }
             },
@@ -359,7 +380,7 @@ export class TreeShaker {
                 if (parts?.length) {
                     const full = parts.map(p => p.text).join('.').toLowerCase();
                     const simple = parts[parts.length - 1].text.toLowerCase();
-                    if (this.allFunctions.has(full) || this.allFunctions.has(simple)) {
+                    if (this.allFunctions.has(full) || this.allSimpleNames.has(simple)) {
                         this.calledNames.add(full);
                         this.calledNames.add(simple);
                     }
@@ -384,10 +405,18 @@ export class TreeShaker {
     // -------------------------------------------------------------------------
 
     /**
-     * Returns true when the function with the given fully-qualified lowercased name
-     * has no known callers and is not a recognized entry point.
+     * Returns true when the function has no known callers and is not a recognized entry point.
+     *
+     * Three name forms are checked against each relevant set:
+     *   bsName     — fully-qualified BrighterScript name (e.g. "utils.helper")
+     *   simpleName — final dot-segment (e.g. "helper")
+     *   brsName    — transpiled BrightScript name (e.g. "utils_helper")
+     *
+     * The brsName check is required because .brs files call functions by their transpiled
+     * underscore name (e.g. utils_helper()), which lands in calledNames/stringRefs as
+     * "utils_helper" — a form that neither bsName nor simpleName would match.
      */
-    isUnused(bsName: string): boolean {
+    isUnused(bsName: string, brsName: string): boolean {
         const simpleName = bsName.split('.').pop() ?? bsName;
         return (
             !this.keepCommented.has(bsName) &&
@@ -396,10 +425,13 @@ export class TreeShaker {
             !TreeShaker.ENTRY_POINTS.has(bsName) &&
             !this.calledNames.has(bsName) &&
             !this.calledNames.has(simpleName) &&
+            !this.calledNames.has(brsName) &&
             !this.stringRefs.has(bsName) &&
             !this.stringRefs.has(simpleName) &&
+            !this.stringRefs.has(brsName) &&
             !this.xmlInterfaceFunctions.has(bsName) &&
-            !this.xmlInterfaceFunctions.has(simpleName)
+            !this.xmlInterfaceFunctions.has(simpleName) &&
+            !this.xmlInterfaceFunctions.has(brsName)
         );
     }
 

From 421d77b348b9903ed965f9b72dcbfbb41e8013a7 Mon Sep 17 00:00:00 2001
From: Tyler Smith <tyler@tksssoftware.com>
Date: Wed, 18 Mar 2026 16:11:07 -0300
Subject: [PATCH 18/44] fix shorthand conflict

---
 src/bscPlugin/treeShaker/TreeShaker.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/bscPlugin/treeShaker/TreeShaker.ts b/src/bscPlugin/treeShaker/TreeShaker.ts
index 6dd1b20c6..459d5868e 100644
--- a/src/bscPlugin/treeShaker/TreeShaker.ts
+++ b/src/bscPlugin/treeShaker/TreeShaker.ts
@@ -240,7 +240,7 @@ export class TreeShaker {
                 if (bsName && brsName) {
                     this.allFunctions.set(bsName, brsName);
                     this.allSimpleNames.add(bsName.split('.').pop()!);
-                    this.allStatements.push({ bsName, brsName, stmt, file });
+                    this.allStatements.push({ bsName: bsName, brsName: brsName, stmt: stmt, file: file });
                     collected.push({ bsName: bsName, brsName: brsName, stmt: stmt });
                 }
             }

From 1f32d43b5fca022f87d8c807e595238cbbac72c8 Mon Sep 17 00:00:00 2001
From: Tyler Smith <tyler@tksssoftware.com>
Date: Wed, 18 Mar 2026 17:28:05 -0300
Subject: [PATCH 19/44] Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
---
 src/bscPlugin/treeShaker/TreeShaker.ts | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/src/bscPlugin/treeShaker/TreeShaker.ts b/src/bscPlugin/treeShaker/TreeShaker.ts
index 459d5868e..85ac7c9d5 100644
--- a/src/bscPlugin/treeShaker/TreeShaker.ts
+++ b/src/bscPlugin/treeShaker/TreeShaker.ts
@@ -418,11 +418,17 @@ export class TreeShaker {
      */
     isUnused(bsName: string, brsName: string): boolean {
         const simpleName = bsName.split('.').pop() ?? bsName;
+        const isGlobalName = !bsName.includes('.');
+        const isEntryPoint =
+            (isGlobalName && TreeShaker.ENTRY_POINTS.has(simpleName)) ||
+            TreeShaker.ENTRY_POINTS.has(brsName);
+        if (isEntryPoint) {
+            // Lifecycle entry points are always considered used.
+            return false;
+        }
         return (
             !this.keepCommented.has(bsName) &&
             !this.keepCommented.has(simpleName) &&
-            !TreeShaker.ENTRY_POINTS.has(simpleName) &&
-            !TreeShaker.ENTRY_POINTS.has(bsName) &&
             !this.calledNames.has(bsName) &&
             !this.calledNames.has(simpleName) &&
             !this.calledNames.has(brsName) &&

From 4879eb7e41f9340725cdca05dc2ef3cf6ee4172f Mon Sep 17 00:00:00 2001
From: Tyler Smith <tyler@tksssoftware.com>
Date: Wed, 18 Mar 2026 17:28:17 -0300
Subject: [PATCH 20/44] Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
---
 docs/shaking.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docs/shaking.md b/docs/shaking.md
index 1fadd0a3e..2bd0393e5 100644
--- a/docs/shaking.md
+++ b/docs/shaking.md
@@ -44,6 +44,7 @@ The following Roku framework callbacks are **always kept** regardless of whether
 | `onMessage` | Task/port message handling |
 | `runUserInterface` | UI task entry point |
 | `runTask` | Background task entry point |
+| `runScreenSaver` | Screensaver entry point |
 
 ## `bs:keep` Comments
 

From 18f7fd5579931fae1acf4e50ac39b132c06fe1ec Mon Sep 17 00:00:00 2001
From: Tyler Smith <tyler@tksssoftware.com>
Date: Wed, 18 Mar 2026 17:28:32 -0300
Subject: [PATCH 21/44] Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
---
 src/bscPlugin/treeShaker/TreeShaker.ts | 20 +++++++++++++++-----
 1 file changed, 15 insertions(+), 5 deletions(-)

diff --git a/src/bscPlugin/treeShaker/TreeShaker.ts b/src/bscPlugin/treeShaker/TreeShaker.ts
index 85ac7c9d5..d6c90d8ce 100644
--- a/src/bscPlugin/treeShaker/TreeShaker.ts
+++ b/src/bscPlugin/treeShaker/TreeShaker.ts
@@ -331,11 +331,21 @@ export class TreeShaker {
             CallExpression: (call) => {
                 const parts = util.getAllDottedGetParts(call.callee);
                 if (parts?.length) {
-                    // Keep both the fully-qualified name and just the final segment
-                    const full = parts.map(p => p.text).join('.').toLowerCase();
-                    const simple = parts[parts.length - 1].text.toLowerCase();
-                    this.calledNames.add(full);
-                    this.calledNames.add(simple);
+                    if (parts.length === 1) {
+                        // Simple/unqualified call, e.g. `foo()`
+                        const simple = parts[0].text.toLowerCase();
+                        if (this.allFunctions.has(simple) || this.allSimpleNames.has(simple)) {
+                            this.calledNames.add(simple);
+                        }
+                    } else {
+                        // Namespaced/dotted call, e.g. `ns.helper()` or `m.top.observeField()`
+                        const full = parts.map(p => p.text).join('.').toLowerCase();
+                        const simple = parts[parts.length - 1].text.toLowerCase();
+                        if (this.allFunctions.has(full) || this.allSimpleNames.has(simple)) {
+                            this.calledNames.add(full);
+                            this.calledNames.add(simple);
+                        }
+                    }
                 }
             },
 

From cf64d4ca8c13449ebfe8eccf51292834ab45cf51 Mon Sep 17 00:00:00 2001
From: Tyler Smith <tyler@tksssoftware.com>
Date: Thu, 19 Mar 2026 08:15:33 -0300
Subject: [PATCH 22/44] fix bug

---
 src/bscPlugin/treeShaker/TreeShaker.ts | 23 ++++++++---------------
 1 file changed, 8 insertions(+), 15 deletions(-)

diff --git a/src/bscPlugin/treeShaker/TreeShaker.ts b/src/bscPlugin/treeShaker/TreeShaker.ts
index d6c90d8ce..3d02aa6c2 100644
--- a/src/bscPlugin/treeShaker/TreeShaker.ts
+++ b/src/bscPlugin/treeShaker/TreeShaker.ts
@@ -331,21 +331,14 @@ export class TreeShaker {
             CallExpression: (call) => {
                 const parts = util.getAllDottedGetParts(call.callee);
                 if (parts?.length) {
-                    if (parts.length === 1) {
-                        // Simple/unqualified call, e.g. `foo()`
-                        const simple = parts[0].text.toLowerCase();
-                        if (this.allFunctions.has(simple) || this.allSimpleNames.has(simple)) {
-                            this.calledNames.add(simple);
-                        }
-                    } else {
-                        // Namespaced/dotted call, e.g. `ns.helper()` or `m.top.observeField()`
-                        const full = parts.map(p => p.text).join('.').toLowerCase();
-                        const simple = parts[parts.length - 1].text.toLowerCase();
-                        if (this.allFunctions.has(full) || this.allSimpleNames.has(simple)) {
-                            this.calledNames.add(full);
-                            this.calledNames.add(simple);
-                        }
-                    }
+                    // Always record the call target unconditionally. Gating on known
+                    // function names would miss transpiled underscore calls from .brs
+                    // files (e.g. utils_helper()) since that form doesn't appear in
+                    // allFunctions or allSimpleNames.
+                    const full = parts.map(p => p.text).join('.').toLowerCase();
+                    const simple = parts[parts.length - 1].text.toLowerCase();
+                    this.calledNames.add(full);
+                    this.calledNames.add(simple);
                 }
             },
 

From de7dece9e3eb20f9ddea44ba7c6e1ee1f1dcb009 Mon Sep 17 00:00:00 2001
From: Tyler Smith <tyler@tksssoftware.com>
Date: Thu, 19 Mar 2026 08:27:35 -0300
Subject: [PATCH 23/44] Windows src path normalization

---
 src/bscPlugin/treeShaker/TreeShaker.ts | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/src/bscPlugin/treeShaker/TreeShaker.ts b/src/bscPlugin/treeShaker/TreeShaker.ts
index 3d02aa6c2..de3886f3e 100644
--- a/src/bscPlugin/treeShaker/TreeShaker.ts
+++ b/src/bscPlugin/treeShaker/TreeShaker.ts
@@ -169,7 +169,10 @@ export class TreeShaker {
                     const resolved = path.isAbsolute(pattern)
                         ? pattern
                         : path.resolve(this.rootDir, pattern);
-                    return new minimatch.Minimatch(util.standardizePath(resolved), { nocase: true });
+                    // Normalize to forward slashes: util.standardizePath uses path.win32.normalize
+                    // which produces backslashes on Windows, and minimatch treats \ as an escape
+                    // character rather than a path separator unless paths are normalized first.
+                    return new minimatch.Minimatch(util.standardizePath(resolved).replace(/\\/g, '/'), { nocase: true });
                 });
             }
 
@@ -200,7 +203,7 @@ export class TreeShaker {
         if (!cached) {
             const rawPkg = file.pkgPath.replace(/\\/g, '/');
             cached = {
-                srcPath: util.standardizePath(file.srcPath),
+                srcPath: util.standardizePath(file.srcPath).replace(/\\/g, '/'),
                 pkgPath: rawPkg.replace(/\.bs$/i, '.brs')
             };
             this.filePathCache.set(file, cached);

From 0569d01decb9be67f725c65fe6f730df10900272 Mon Sep 17 00:00:00 2001
From: Tyler Smith <tyler@tksssoftware.com>
Date: Thu, 19 Mar 2026 08:28:00 -0300
Subject: [PATCH 24/44] Tree shaking now lives in
 Program.beforeProgramTranspile

---
 src/Program.ts             | 17 +++++++++++++++++
 src/bscPlugin/BscPlugin.ts | 17 ++---------------
 2 files changed, 19 insertions(+), 15 deletions(-)

diff --git a/src/Program.ts b/src/Program.ts
index 33158af17..527b60ddb 100644
--- a/src/Program.ts
+++ b/src/Program.ts
@@ -24,6 +24,7 @@ import { isBrsFile, isXmlFile, isXmlScope, isNamespaceStatement } from './astUti
 import type { FunctionStatement, NamespaceStatement } from './parser/Statement';
 import { BscPlugin } from './bscPlugin/BscPlugin';
 import { AstEditor } from './astUtils/AstEditor';
+import { TreeShaker } from './bscPlugin/treeShaker/TreeShaker';
 import type { SourceMapGenerator } from 'source-map';
 import type { Statement } from './parser/AstNode';
 import { CallExpressionInfo } from './bscPlugin/CallExpressionInfo';
@@ -73,6 +74,8 @@ export class Program {
         //inject the bsc plugin as the first plugin in the stack.
         this.plugins.addFirst(new BscPlugin());
 
+        this.treeShaker = new TreeShaker();
+
         //normalize the root dir path
         this.options.rootDir = util.getRootDir(this.options);
 
@@ -119,6 +122,8 @@ export class Program {
      */
     public plugins: PluginInterface;
 
+    private treeShaker: TreeShaker;
+
     /**
      * A set of diagnostics. This does not include any of the scope diagnostics.
      * Should only be set from `this.validate()`
@@ -1311,6 +1316,18 @@ export class Program {
         const astEditor = new AstEditor();
 
         this.plugins.emit('beforeProgramTranspile', this, entries, astEditor);
+
+        // Tree shaking runs after all plugins so it sees the fully-transformed AST.
+        // Running it inside BscPlugin (which is addFirst) would mean it executes before
+        // user plugins' beforeProgramTranspile hooks, causing functions added or referenced
+        // by those plugins to be incorrectly removed.
+        if (this.options.treeShaking.enabled) {
+            this.treeShaker.analyze(this, this.options.treeShaking.keep);
+            for (const entry of entries) {
+                this.treeShaker.shake(entry.file, astEditor);
+            }
+        }
+
         return {
             entries: entries,
             getOutputPath: getOutputPath,
diff --git a/src/bscPlugin/BscPlugin.ts b/src/bscPlugin/BscPlugin.ts
index 30d2deab1..386326f38 100644
--- a/src/bscPlugin/BscPlugin.ts
+++ b/src/bscPlugin/BscPlugin.ts
@@ -1,7 +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, TranspileObj } from '../Program';
+import type { Program } from '../Program';
 import { CodeActionsProcessor } from './codeActions/CodeActionsProcessor';
 import { CompletionsProcessor } from './completions/CompletionsProcessor';
 import { DefinitionProvider } from './definition/DefinitionProvider';
@@ -15,7 +15,6 @@ 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';
@@ -62,18 +61,6 @@ 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) {

From 5ca9b743cfdfd6c5eccf2102372e2a7ffe1a8f2d Mon Sep 17 00:00:00 2001
From: Tyler Smith <tyler@tksssoftware.com>
Date: Thu, 19 Mar 2026 08:35:34 -0300
Subject: [PATCH 25/44] remove space

---
 src/bscPlugin/BscPlugin.ts | 1 -
 1 file changed, 1 deletion(-)

diff --git a/src/bscPlugin/BscPlugin.ts b/src/bscPlugin/BscPlugin.ts
index 386326f38..5922a0599 100644
--- a/src/bscPlugin/BscPlugin.ts
+++ b/src/bscPlugin/BscPlugin.ts
@@ -1,5 +1,4 @@
 import { isBrsFile, isXmlFile } from '../astUtils/reflection';
-
 import type { BeforeFileTranspileEvent, Plugin, OnFileValidateEvent, OnGetCodeActionsEvent, ProvideHoverEvent, OnGetSemanticTokensEvent, OnScopeValidateEvent, ProvideCompletionsEvent, ProvideDefinitionEvent, ProvideReferencesEvent, ProvideDocumentSymbolsEvent, ProvideWorkspaceSymbolsEvent } from '../interfaces';
 import type { Program } from '../Program';
 import { CodeActionsProcessor } from './codeActions/CodeActionsProcessor';

From 42967780251769e1e2c19d312379ae3d42f55fef Mon Sep 17 00:00:00 2001
From: Tyler Smith <tyler@tksssoftware.com>
Date: Thu, 19 Mar 2026 08:46:31 -0300
Subject: [PATCH 26/44] Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
---
 src/util.ts | 17 +++++++++++++++--
 1 file changed, 15 insertions(+), 2 deletions(-)

diff --git a/src/util.ts b/src/util.ts
index 33c4a35e0..47e1f90b4 100644
--- a/src/util.ts
+++ b/src/util.ts
@@ -376,6 +376,9 @@ export class Util {
             bslibDestinationDir = bslibDestinationDir.replace(/^(\/*)(.*?)(\/*)$/, '$2');
         }
 
+        // compute an initial normalized treeShaking config; this will be kept normalized
+        let normalizedTreeShaking = this.normalizeTreeShakingConfig(config.treeShaking);
+
         const configWithDefaults: Omit<FinalizedBsConfig, 'rootDir'> = {
             cwd: cwd,
             deploy: config.deploy === true ? true : false,
@@ -404,12 +407,22 @@ export class Util {
             removeParameterTypes: config.removeParameterTypes === true ? true : false,
             logLevel: logLevel,
             bslibDestinationDir: bslibDestinationDir,
-            treeShaking: this.normalizeTreeShakingConfig(config.treeShaking)
+            treeShaking: normalizedTreeShaking
         };
 
         //mutate `config` in case anyone is holding a reference to the incomplete one
         const merged: FinalizedBsConfig = Object.assign(config, configWithDefaults);
 
+        // ensure treeShaking remains normalized even if overwritten later (e.g. by merges)
+        Object.defineProperty(merged, 'treeShaking', {
+            get: () => normalizedTreeShaking,
+            set: (value: TreeShakingConfig | NormalizedTreeShakingConfig | undefined) => {
+                normalizedTreeShaking = this.normalizeTreeShakingConfig(value as any);
+            },
+            enumerable: true,
+            configurable: true
+        });
+
         return merged;
     }
 
@@ -419,7 +432,7 @@ export class Util {
      * - Scalar `src`/`dest`/`functions`/`matches` values are wrapped in arrays.
      * - Object rules that contain none of the known fields are silently skipped.
      */
-    private normalizeTreeShakingConfig(config?: TreeShakingConfig): NormalizedTreeShakingConfig {
+    private normalizeTreeShakingConfig(config?: TreeShakingConfig | NormalizedTreeShakingConfig): NormalizedTreeShakingConfig {
         const enabled = config?.enabled === true;
         const keep: NormalizedKeepRule[] = [];
 

From ff2d8dfe03088cf7b1a0b87a1ae83494d8a7bd12 Mon Sep 17 00:00:00 2001
From: Tyler Smith <tyler@tksssoftware.com>
Date: Thu, 19 Mar 2026 08:49:21 -0300
Subject: [PATCH 27/44] Move TreeShaker

---
 src/Program.ts                                |   2 +-
 .../treeShaker/TreeShaker.spec.ts             | 153 +++++++++++++++++-
 src/{bscPlugin => }/treeShaker/TreeShaker.ts  |  26 +--
 3 files changed, 164 insertions(+), 17 deletions(-)
 rename src/{bscPlugin => }/treeShaker/TreeShaker.spec.ts (87%)
 rename src/{bscPlugin => }/treeShaker/TreeShaker.ts (97%)

diff --git a/src/Program.ts b/src/Program.ts
index 527b60ddb..57c48f342 100644
--- a/src/Program.ts
+++ b/src/Program.ts
@@ -24,7 +24,7 @@ import { isBrsFile, isXmlFile, isXmlScope, isNamespaceStatement } from './astUti
 import type { FunctionStatement, NamespaceStatement } from './parser/Statement';
 import { BscPlugin } from './bscPlugin/BscPlugin';
 import { AstEditor } from './astUtils/AstEditor';
-import { TreeShaker } from './bscPlugin/treeShaker/TreeShaker';
+import { TreeShaker } from './treeShaker/TreeShaker';
 import type { SourceMapGenerator } from 'source-map';
 import type { Statement } from './parser/AstNode';
 import { CallExpressionInfo } from './bscPlugin/CallExpressionInfo';
diff --git a/src/bscPlugin/treeShaker/TreeShaker.spec.ts b/src/treeShaker/TreeShaker.spec.ts
similarity index 87%
rename from src/bscPlugin/treeShaker/TreeShaker.spec.ts
rename to src/treeShaker/TreeShaker.spec.ts
index 0a6c3a302..a588b105c 100644
--- a/src/bscPlugin/treeShaker/TreeShaker.spec.ts
+++ b/src/treeShaker/TreeShaker.spec.ts
@@ -1,6 +1,6 @@
-import { expect } from '../../chai-config.spec';
-import { Program } from '../../Program';
-import { standardizePath as s } from '../../util';
+import { expect } from '../chai-config.spec';
+import { Program } from '../Program';
+import { standardizePath as s } from '../util';
 import * as fsExtra from 'fs-extra';
 import undent from 'undent';
 
@@ -80,6 +80,9 @@ describe('TreeShaker', () => {
                 sub runTask()
                 end sub
 
+                sub runScreenSaver()
+                end sub
+
                 sub onMessage()
                 end sub
 
@@ -93,6 +96,7 @@ describe('TreeShaker', () => {
             expect(code).to.include('sub onKeyEvent(');
             expect(code).to.include('sub runUserInterface()');
             expect(code).to.include('sub runTask()');
+            expect(code).to.include('sub runScreenSaver()');
             expect(code).to.include('sub onMessage()');
             expect(code).not.to.include('sub removable()');
         });
@@ -339,6 +343,64 @@ describe('TreeShaker', () => {
             expect(code).not.to.include('sub unused()');
         });
 
+        it('preserves a namespaced function referenced as a string literal using its transpiled brs name', async () => {
+            // observeField("x", "utils_helper") — the string value is the transpiled brsName,
+            // not the BrighterScript dotted name. stringRefs must match against brsName.
+            program.setFile('source/utils.bs', `
+                namespace utils
+                    sub helper()
+                        print "referenced by transpiled name in string"
+                    end sub
+
+                    sub unused()
+                    end sub
+                end namespace
+            `);
+            program.setFile('source/main.bs', `
+                sub init()
+                    m.top.observeField("data", "utils_helper")
+                end sub
+
+                sub main()
+                end sub
+            `);
+
+            const code = await getTranspiled('source/utils.bs');
+            expect(code).to.include('utils_helper');
+            expect(code).not.to.include('utils_unused');
+        });
+
+        it('preserves the full bs:keep call chain across multiple files', async () => {
+            program.setFile('source/helpers.bs', `
+                sub middle()
+                    leaf()
+                end sub
+
+                sub leaf()
+                    print "end of cross-file chain"
+                end sub
+            `);
+            program.setFile('source/main.bs', `
+                sub main()
+                end sub
+
+                ' bs:keep
+                sub topLevel()
+                    middle()
+                end sub
+
+                sub unrelated()
+                end sub
+            `);
+
+            const helpersCode = await getTranspiled('source/helpers.bs');
+            const mainCode = await getTranspiled('source/main.bs');
+            expect(mainCode).to.include('sub topLevel()');
+            expect(helpersCode).to.include('sub middle()');
+            expect(helpersCode).to.include('sub leaf()');
+            expect(mainCode).not.to.include('sub unrelated()');
+        });
+
         it('preserves functions passed by reference as variables', async () => {
             program.setFile('source/main.bs', `
                 sub init()
@@ -757,6 +819,31 @@ describe('TreeShaker', () => {
                 expect(code).not.to.include('sub removeMe()');
             });
 
+            it('keeps a namespaced function matched by its transpiled brs name in the functions array', async () => {
+                program = new Program({
+                    rootDir: rootDir, stagingDir: stagingDir,
+                    treeShaking: { enabled: true, keep: [{ functions: ['utils_helper'] }] }
+                });
+                program.setFile('source/main.bs', `
+                    namespace utils
+                        sub helper()
+                            print "kept by brs name in functions rule"
+                        end sub
+
+                        sub gone()
+                            print "removed"
+                        end sub
+                    end namespace
+
+                    sub main()
+                    end sub
+                `);
+
+                const code = await getTranspiled('source/main.bs');
+                expect(code).to.include('utils_helper');
+                expect(code).not.to.include('utils_gone');
+            });
+
             it('is case-insensitive for function names', async () => {
                 program = new Program({
                     rootDir: rootDir, stagingDir: stagingDir,
@@ -867,6 +954,36 @@ describe('TreeShaker', () => {
                 expect(mainCode).not.to.include('sub appHelper()');
             });
 
+            it('keeps functions from any path when dest is an array of globs', async () => {
+                program = new Program({
+                    rootDir: rootDir, stagingDir: stagingDir,
+                    treeShaking: { enabled: true, keep: [{ dest: ['source/libA.brs', 'source/libB.brs'] }] }
+                });
+                program.setFile('source/libA.bs', `
+                    sub fromA()
+                    end sub
+                `);
+                program.setFile('source/libB.bs', `
+                    sub fromB()
+                    end sub
+                `);
+                program.setFile('source/main.bs', `
+                    sub main()
+                    end sub
+
+                    sub appOnly()
+                    end sub
+                `);
+
+                const codeA = await getTranspiled('source/libA.bs');
+                const codeB = await getTranspiled('source/libB.bs');
+                const mainCode = await getTranspiled('source/main.bs');
+
+                expect(codeA).to.include('sub fromA()');
+                expect(codeB).to.include('sub fromB()');
+                expect(mainCode).not.to.include('sub appOnly()');
+            });
+
             it('accepts a pkg:/ prefix in dest patterns and strips it before matching', async () => {
                 program = new Program({
                     rootDir: rootDir, stagingDir: stagingDir,
@@ -1028,6 +1145,36 @@ describe('TreeShaker', () => {
                 expect(code).to.include('sub innerHelper()');
                 expect(code).not.to.include('sub unrelated()');
             });
+
+            it('preserves transitive callees of a kept function across files', async () => {
+                program = new Program({
+                    rootDir: rootDir, stagingDir: stagingDir,
+                    treeShaking: { enabled: true, keep: ['entryPoint'] }
+                });
+                program.setFile('source/helpers.bs', `
+                    sub crossFileHelper()
+                        print "required by entryPoint"
+                    end sub
+
+                    sub unreachable()
+                        print "no connection to entryPoint"
+                    end sub
+                `);
+                program.setFile('source/main.bs', `
+                    sub main()
+                    end sub
+
+                    sub entryPoint()
+                        crossFileHelper()
+                    end sub
+                `);
+
+                const helpersCode = await getTranspiled('source/helpers.bs');
+                const mainCode = await getTranspiled('source/main.bs');
+                expect(mainCode).to.include('sub entryPoint()');
+                expect(helpersCode).to.include('sub crossFileHelper()');
+                expect(helpersCode).not.to.include('sub unreachable()');
+            });
         });
 
         describe('matches with multiple patterns', () => {
diff --git a/src/bscPlugin/treeShaker/TreeShaker.ts b/src/treeShaker/TreeShaker.ts
similarity index 97%
rename from src/bscPlugin/treeShaker/TreeShaker.ts
rename to src/treeShaker/TreeShaker.ts
index de3886f3e..97d2e442f 100644
--- a/src/bscPlugin/treeShaker/TreeShaker.ts
+++ b/src/treeShaker/TreeShaker.ts
@@ -1,18 +1,18 @@
 import * as minimatch from 'minimatch';
 import * as path from 'path';
-import type { AstEditor } from '../../astUtils/AstEditor';
-import { isBrsFile, isDottedGetExpression, isLiteralString, isXmlFile } from '../../astUtils/reflection';
-import { WalkMode, createVisitor } from '../../astUtils/visitors';
-import type { BrsFile } from '../../files/BrsFile';
-import type { XmlFile } from '../../files/XmlFile';
-import type { NormalizedKeepRule } from '../../BsConfig';
-import type { BscFile } from '../../interfaces';
-import type { CallfuncExpression } from '../../parser/Expression';
-import { ParseMode } from '../../parser/Parser';
-import { EmptyStatement } from '../../parser/Statement';
-import type { FunctionStatement } from '../../parser/Statement';
-import type { Program } from '../../Program';
-import util from '../../util';
+import type { AstEditor } from '../astUtils/AstEditor';
+import { isBrsFile, isDottedGetExpression, isLiteralString, isXmlFile } from '../astUtils/reflection';
+import { WalkMode, createVisitor } from '../astUtils/visitors';
+import type { BrsFile } from '../files/BrsFile';
+import type { XmlFile } from '../files/XmlFile';
+import type { NormalizedKeepRule } from '../BsConfig';
+import type { BscFile } from '../interfaces';
+import type { CallfuncExpression } from '../parser/Expression';
+import { ParseMode } from '../parser/Parser';
+import { EmptyStatement } from '../parser/Statement';
+import type { FunctionStatement } from '../parser/Statement';
+import type { Program } from '../Program';
+import util from '../util';
 
 /**
  * Keep rule with patterns pre-compiled and src paths pre-resolved.

From edd9cea86a9ad48cc0235973e87881e35905a8f9 Mon Sep 17 00:00:00 2001
From: Tyler Smith <tyler@tksssoftware.com>
Date: Thu, 19 Mar 2026 09:00:48 -0300
Subject: [PATCH 28/44] Updated comment

---
 src/Program.ts | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/src/Program.ts b/src/Program.ts
index 57c48f342..02eb8bc10 100644
--- a/src/Program.ts
+++ b/src/Program.ts
@@ -1317,10 +1317,9 @@ export class Program {
 
         this.plugins.emit('beforeProgramTranspile', this, entries, astEditor);
 
-        // Tree shaking runs after all plugins so it sees the fully-transformed AST.
-        // Running it inside BscPlugin (which is addFirst) would mean it executes before
-        // user plugins' beforeProgramTranspile hooks, causing functions added or referenced
-        // by those plugins to be incorrectly removed.
+        // Tree shaking runs after all plugins' beforeProgramTranspile hooks so it sees
+        // any functions added or referenced by user plugins. Note: beforeFileTranspile
+        // hooks still run later per-file and are not visible to the shaker.
         if (this.options.treeShaking.enabled) {
             this.treeShaker.analyze(this, this.options.treeShaking.keep);
             for (const entry of entries) {

From 301a91990e77ce4c017cbde3fe8f6a865d2a967c Mon Sep 17 00:00:00 2001
From: Tyler Smith <tyler@tksssoftware.com>
Date: Thu, 19 Mar 2026 09:16:17 -0300
Subject: [PATCH 29/44] Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
---
 src/treeShaker/TreeShaker.ts | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/src/treeShaker/TreeShaker.ts b/src/treeShaker/TreeShaker.ts
index 97d2e442f..35586aa7e 100644
--- a/src/treeShaker/TreeShaker.ts
+++ b/src/treeShaker/TreeShaker.ts
@@ -503,9 +503,16 @@ export class TreeShaker {
             return;
         }
 
+        let removedAny = false;
+
         file.ast.walk(createVisitor({
             FunctionStatement: (stmt) => {
                 if (this.toRemove.has(stmt)) {
+                    if (!removedAny) {
+                        // ensure modified AST is emitted for .brs files
+                        editor.setProperty(file, 'needsTranspiled', true);
+                        removedAny = true;
+                    }
                     return new EmptyStatement();
                 }
             }

From 12643fd1fd1312974f371eb4f4b5f00bde4f7337 Mon Sep 17 00:00:00 2001
From: Tyler Smith <tyler@tksssoftware.com>
Date: Thu, 19 Mar 2026 09:55:41 -0300
Subject: [PATCH 30/44] logging

---
 src/treeShaker/TreeShaker.ts | 15 ++++++++++++---
 1 file changed, 12 insertions(+), 3 deletions(-)

diff --git a/src/treeShaker/TreeShaker.ts b/src/treeShaker/TreeShaker.ts
index 35586aa7e..0d4d8a0ad 100644
--- a/src/treeShaker/TreeShaker.ts
+++ b/src/treeShaker/TreeShaker.ts
@@ -13,6 +13,7 @@ import { EmptyStatement } from '../parser/Statement';
 import type { FunctionStatement } from '../parser/Statement';
 import type { Program } from '../Program';
 import util from '../util';
+import type { Logger } from '../logging';
 
 /**
  * Keep rule with patterns pre-compiled and src paths pre-resolved.
@@ -87,6 +88,9 @@ export class TreeShaker {
     // Resolved rootDir for src-path matching
     private rootDir = '';
 
+    // Logger sourced from the Program — set at the start of analyze()
+    private logger: Logger | undefined;
+
     reset() {
         this.allFunctions.clear();
         this.allSimpleNames.clear();
@@ -119,6 +123,7 @@ export class TreeShaker {
      */
     analyze(program: Program, keepRules: NormalizedKeepRule[]) {
         this.reset();
+        this.logger = program.logger;
         this.rootDir = program.options.rootDir ?? process.cwd();
 
         // Compile patterns and resolve src paths once — before any per-function work
@@ -503,19 +508,23 @@ export class TreeShaker {
             return;
         }
 
-        let removedAny = false;
+        const removed: string[] = [];
 
         file.ast.walk(createVisitor({
             FunctionStatement: (stmt) => {
                 if (this.toRemove.has(stmt)) {
-                    if (!removedAny) {
+                    if (removed.length === 0) {
                         // ensure modified AST is emitted for .brs files
                         editor.setProperty(file, 'needsTranspiled', true);
-                        removedAny = true;
                     }
+                    removed.push(stmt.getName(ParseMode.BrightScript) ?? '?');
                     return new EmptyStatement();
                 }
             }
         }), { walkMode: WalkMode.visitStatements, editor: editor });
+
+        if (removed.length > 0) {
+            this.logger?.debug(`tree shaker removed ${removed.length} function(s) from ${file.pkgPath}: ${removed.join(', ')}`);
+        }
     }
 }

From b6d9d57a1eed13d5ea220a4679354c9983af1f72 Mon Sep 17 00:00:00 2001
From: Tyler Smith <tyler@tksssoftware.com>
Date: Thu, 19 Mar 2026 10:10:04 -0300
Subject: [PATCH 31/44] fix(tree-shaker): retain .brs library functions called
 via namespace syntax

---
 src/treeShaker/TreeShaker.spec.ts | 33 +++++++++++++++++++++++++++++++
 src/treeShaker/TreeShaker.ts      |  7 +++++++
 2 files changed, 40 insertions(+)

diff --git a/src/treeShaker/TreeShaker.spec.ts b/src/treeShaker/TreeShaker.spec.ts
index a588b105c..bbbc678b1 100644
--- a/src/treeShaker/TreeShaker.spec.ts
+++ b/src/treeShaker/TreeShaker.spec.ts
@@ -401,6 +401,39 @@ describe('TreeShaker', () => {
             expect(mainCode).not.to.include('sub unrelated()');
         });
 
+        it('preserves a pre-compiled .brs library function called via namespace syntax from a .bs file', async () => {
+            // The .brs file defines sub promises_chain(...) — no namespace statement.
+            // The .bs file calls it as promises.chain(...) which BrighterScript transpiles
+            // to promises_chain(...). calledNames receives 'promises.chain' and 'chain',
+            // but bsName for the .brs function is 'promises_chain' (no dots). Without also
+            // recording the underscore-joined form, isUnused would incorrectly remove it.
+            program.setFile('source/promises.brs', `
+                function promises_chain(task as object) as object
+                    return { then: promises_then }
+                end function
+
+                function promises_then(callback as object) as object
+                    return invalid
+                end function
+            `);
+            program.setFile('source/main.bs', `
+                namespace promises
+                    function chain(task as object) as object
+                    end function
+                end namespace
+
+                sub main()
+                    promises.chain(doWork())
+                end sub
+
+                sub doWork()
+                end sub
+            `);
+
+            const code = await getTranspiled('source/promises.brs');
+            expect(code).to.include('promises_chain');
+        });
+
         it('preserves functions passed by reference as variables', async () => {
             program.setFile('source/main.bs', `
                 sub init()
diff --git a/src/treeShaker/TreeShaker.ts b/src/treeShaker/TreeShaker.ts
index 0d4d8a0ad..c80f2d27e 100644
--- a/src/treeShaker/TreeShaker.ts
+++ b/src/treeShaker/TreeShaker.ts
@@ -347,6 +347,13 @@ export class TreeShaker {
                     const simple = parts[parts.length - 1].text.toLowerCase();
                     this.calledNames.add(full);
                     this.calledNames.add(simple);
+                    // Also record the underscore-joined form so that namespace calls like
+                    // promises.chain() correctly retain a pre-compiled .brs library function
+                    // named promises_chain. Without this, bsName='promises_chain' would not
+                    // match calledNames={'promises.chain','chain'} and would be removed.
+                    if (parts.length > 1) {
+                        this.calledNames.add(parts.map(p => p.text).join('_').toLowerCase());
+                    }
                 }
             },
 

From bbc8752ef5ecffe0e1eee12fb9d5c2df16b8f5e4 Mon Sep 17 00:00:00 2001
From: Tyler Smith <tyler@tksssoftware.com>
Date: Thu, 19 Mar 2026 13:06:00 -0300
Subject: [PATCH 32/44] move logging to single output

---
 src/Program.ts               |  1 +
 src/treeShaker/TreeShaker.ts | 21 ++++++++++++++++++++-
 2 files changed, 21 insertions(+), 1 deletion(-)

diff --git a/src/Program.ts b/src/Program.ts
index 02eb8bc10..73a337b47 100644
--- a/src/Program.ts
+++ b/src/Program.ts
@@ -1325,6 +1325,7 @@ export class Program {
             for (const entry of entries) {
                 this.treeShaker.shake(entry.file, astEditor);
             }
+            this.treeShaker.logSummary();
         }
 
         return {
diff --git a/src/treeShaker/TreeShaker.ts b/src/treeShaker/TreeShaker.ts
index c80f2d27e..5014660c0 100644
--- a/src/treeShaker/TreeShaker.ts
+++ b/src/treeShaker/TreeShaker.ts
@@ -91,6 +91,9 @@ export class TreeShaker {
     // Logger sourced from the Program — set at the start of analyze()
     private logger: Logger | undefined;
 
+    // Removals accumulated across shake() calls — keyed by pkgPath for the summary log
+    private removalLog = new Map<string, string[]>();
+
     reset() {
         this.allFunctions.clear();
         this.allSimpleNames.clear();
@@ -103,6 +106,7 @@ export class TreeShaker {
         this.filePathCache.clear();
         this.toRemove.clear();
         this.rootDir = '';
+        this.removalLog.clear();
     }
 
     /**
@@ -531,7 +535,22 @@ export class TreeShaker {
         }), { walkMode: WalkMode.visitStatements, editor: editor });
 
         if (removed.length > 0) {
-            this.logger?.debug(`tree shaker removed ${removed.length} function(s) from ${file.pkgPath}: ${removed.join(', ')}`);
+            this.removalLog.set(file.pkgPath, removed);
+        }
+    }
+
+    /**
+     * Log a single consolidated summary of every function removed across all files.
+     * Call this after the shake() loop in Program.beforeProgramTranspile.
+     */
+    logSummary() {
+        if (this.removalLog.size === 0 || !this.logger) {
+            return;
+        }
+        const totalRemoved = [...this.removalLog.values()].reduce((sum, fns) => sum + fns.length, 0);
+        this.logger.log(`tree shaker removed ${totalRemoved} function(s) across ${this.removalLog.size} file(s):`);
+        for (const [pkgPath, fns] of this.removalLog) {
+            this.logger.log(`  ${pkgPath}: ${fns.join(', ')}`);
         }
     }
 }

From 83e0f6b5bf4169c6561826b7919916ca16111e3b Mon Sep 17 00:00:00 2001
From: Tyler Smith <tyler@tksssoftware.com>
Date: Thu, 19 Mar 2026 13:14:03 -0300
Subject: [PATCH 33/44] tests for excludes brs

---
 src/treeShaker/TreeShaker.spec.ts | 44 ++++++++++++++++++++++++++++++-
 1 file changed, 43 insertions(+), 1 deletion(-)

diff --git a/src/treeShaker/TreeShaker.spec.ts b/src/treeShaker/TreeShaker.spec.ts
index bbbc678b1..fda34b5e2 100644
--- a/src/treeShaker/TreeShaker.spec.ts
+++ b/src/treeShaker/TreeShaker.spec.ts
@@ -4,7 +4,7 @@ import { standardizePath as s } from '../util';
 import * as fsExtra from 'fs-extra';
 import undent from 'undent';
 
-describe('TreeShaker', () => {
+describe.only('TreeShaker', () => {
     let program: Program;
     const tempDir = s`${__dirname}/../.tmp`;
     const rootDir = s`${tempDir}/rootDir`;
@@ -927,6 +927,48 @@ describe('TreeShaker', () => {
         });
 
         describe('src rule', () => {
+            it('does not set needsTranspiled on a .brs file fully covered by a src keep rule', async () => {
+                // When every function in a .brs file is kept by a keep rule, shake() never
+                // replaces any statement, so needsTranspiled must stay false. This prevents
+                // the BrighterScript transpiler from running on the file and applying
+                // transformations (e.g. namespace resolution) that corrupt plain BrightScript
+                // code such as `date.AsSeconds()` where `date` is a local variable.
+                program = new Program({
+                    rootDir: rootDir, stagingDir: stagingDir,
+                    treeShaking: { enabled: true, keep: [{ src: '**/SDK.brs' }] }
+                });
+                program.setFile('source/SDK.brs', `
+                    function getCurrentTimeSeconds() as object
+                        date = CreateObject("roDateTime")
+                        return date.AsSeconds()
+                    end function
+
+                    function unusedSdkHelper() as string
+                        return "unused"
+                    end function
+                `);
+                program.setFile('source/main.bs', `
+                    sub main()
+                    end sub
+                `);
+
+                program.validate();
+                // Trigger the shake pass the same way Program.beforeProgramTranspile does
+                const { AstEditor } = require('../astUtils/AstEditor');
+                const editor = new AstEditor();
+                const { isBrsFile } = require('../astUtils/reflection');
+                const { TreeShaker } = require('./TreeShaker');
+                const shaker = new TreeShaker();
+                shaker.analyze(program, program.options.treeShaking.keep);
+
+                const sdkFile = program.getFile('source/SDK.brs');
+                shaker.shake(sdkFile, editor);
+
+                // needsTranspiled must remain false — the file must not be put through
+                // the BrighterScript transpiler since it was fully protected by a keep rule
+                expect((sdkFile as any).needsTranspiled).to.be.false;
+            });
+
             it('keeps all functions in files matching the src glob', async () => {
                 program = new Program({
                     rootDir: rootDir, stagingDir: stagingDir,

From b6f036acb0c9c8684dc8bca144898c777d6bc432 Mon Sep 17 00:00:00 2001
From: Tyler Smith <tyler@tksssoftware.com>
Date: Thu, 19 Mar 2026 13:22:28 -0300
Subject: [PATCH 34/44] Move treeShaker back into BscPlugin.ts

---
 src/Program.ts                                | 16 -----------
 src/bscPlugin/BscPlugin.ts                    | 16 ++++++++++-
 .../treeShaker/TreeShaker.spec.ts             |  9 +++---
 src/{ => bscPlugin}/treeShaker/TreeShaker.ts  | 28 +++++++++----------
 4 files changed, 33 insertions(+), 36 deletions(-)
 rename src/{ => bscPlugin}/treeShaker/TreeShaker.spec.ts (99%)
 rename src/{ => bscPlugin}/treeShaker/TreeShaker.ts (97%)

diff --git a/src/Program.ts b/src/Program.ts
index 73a337b47..7cfbd3759 100644
--- a/src/Program.ts
+++ b/src/Program.ts
@@ -24,7 +24,6 @@ import { isBrsFile, isXmlFile, isXmlScope, isNamespaceStatement } from './astUti
 import type { FunctionStatement, NamespaceStatement } from './parser/Statement';
 import { BscPlugin } from './bscPlugin/BscPlugin';
 import { AstEditor } from './astUtils/AstEditor';
-import { TreeShaker } from './treeShaker/TreeShaker';
 import type { SourceMapGenerator } from 'source-map';
 import type { Statement } from './parser/AstNode';
 import { CallExpressionInfo } from './bscPlugin/CallExpressionInfo';
@@ -74,8 +73,6 @@ export class Program {
         //inject the bsc plugin as the first plugin in the stack.
         this.plugins.addFirst(new BscPlugin());
 
-        this.treeShaker = new TreeShaker();
-
         //normalize the root dir path
         this.options.rootDir = util.getRootDir(this.options);
 
@@ -122,8 +119,6 @@ export class Program {
      */
     public plugins: PluginInterface;
 
-    private treeShaker: TreeShaker;
-
     /**
      * A set of diagnostics. This does not include any of the scope diagnostics.
      * Should only be set from `this.validate()`
@@ -1317,17 +1312,6 @@ export class Program {
 
         this.plugins.emit('beforeProgramTranspile', this, entries, astEditor);
 
-        // Tree shaking runs after all plugins' beforeProgramTranspile hooks so it sees
-        // any functions added or referenced by user plugins. Note: beforeFileTranspile
-        // hooks still run later per-file and are not visible to the shaker.
-        if (this.options.treeShaking.enabled) {
-            this.treeShaker.analyze(this, this.options.treeShaking.keep);
-            for (const entry of entries) {
-                this.treeShaker.shake(entry.file, astEditor);
-            }
-            this.treeShaker.logSummary();
-        }
-
         return {
             entries: entries,
             getOutputPath: getOutputPath,
diff --git a/src/bscPlugin/BscPlugin.ts b/src/bscPlugin/BscPlugin.ts
index 5922a0599..ea22e5403 100644
--- a/src/bscPlugin/BscPlugin.ts
+++ b/src/bscPlugin/BscPlugin.ts
@@ -1,6 +1,8 @@
 import { isBrsFile, isXmlFile } from '../astUtils/reflection';
 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 type { AstEditor } from '../astUtils/AstEditor';
+import { TreeShaker } from './treeShaker/TreeShaker';
 import { CodeActionsProcessor } from './codeActions/CodeActionsProcessor';
 import { CompletionsProcessor } from './completions/CompletionsProcessor';
 import { DefinitionProvider } from './definition/DefinitionProvider';
@@ -18,6 +20,8 @@ import { WorkspaceSymbolProcessor } from './symbols/WorkspaceSymbolProcessor';
 export class BscPlugin implements Plugin {
     public name = 'BscPlugin';
 
+    private treeShaker = new TreeShaker();
+
     public onGetCodeActions(event: OnGetCodeActionsEvent) {
         new CodeActionsProcessor(event).process();
     }
@@ -72,6 +76,16 @@ export class BscPlugin implements Plugin {
         this.scopeValidator.reset();
     }
 
+    public beforeProgramTranspile(program: Program, entries: TranspileObj[], editor: AstEditor) {
+        if (program.options.treeShaking.enabled) {
+            this.treeShaker.analyze(program, program.options.treeShaking.keep);
+            for (const entry of entries) {
+                this.treeShaker.shake(entry.file, editor);
+            }
+            this.treeShaker.logSummary();
+        }
+    }
+
     public beforeFileTranspile(event: BeforeFileTranspileEvent) {
         if (isBrsFile(event.file)) {
             return new BrsFilePreTranspileProcessor(event as any).process();
diff --git a/src/treeShaker/TreeShaker.spec.ts b/src/bscPlugin/treeShaker/TreeShaker.spec.ts
similarity index 99%
rename from src/treeShaker/TreeShaker.spec.ts
rename to src/bscPlugin/treeShaker/TreeShaker.spec.ts
index fda34b5e2..24b578914 100644
--- a/src/treeShaker/TreeShaker.spec.ts
+++ b/src/bscPlugin/treeShaker/TreeShaker.spec.ts
@@ -1,6 +1,6 @@
-import { expect } from '../chai-config.spec';
-import { Program } from '../Program';
-import { standardizePath as s } from '../util';
+import { expect } from '../../chai-config.spec';
+import { Program } from '../../Program';
+import { standardizePath as s } from '../../util';
 import * as fsExtra from 'fs-extra';
 import undent from 'undent';
 
@@ -954,9 +954,8 @@ describe.only('TreeShaker', () => {
 
                 program.validate();
                 // Trigger the shake pass the same way Program.beforeProgramTranspile does
-                const { AstEditor } = require('../astUtils/AstEditor');
+                const { AstEditor } = require('../../astUtils/AstEditor');
                 const editor = new AstEditor();
-                const { isBrsFile } = require('../astUtils/reflection');
                 const { TreeShaker } = require('./TreeShaker');
                 const shaker = new TreeShaker();
                 shaker.analyze(program, program.options.treeShaking.keep);
diff --git a/src/treeShaker/TreeShaker.ts b/src/bscPlugin/treeShaker/TreeShaker.ts
similarity index 97%
rename from src/treeShaker/TreeShaker.ts
rename to src/bscPlugin/treeShaker/TreeShaker.ts
index 5014660c0..eaee3c46c 100644
--- a/src/treeShaker/TreeShaker.ts
+++ b/src/bscPlugin/treeShaker/TreeShaker.ts
@@ -1,19 +1,19 @@
 import * as minimatch from 'minimatch';
 import * as path from 'path';
-import type { AstEditor } from '../astUtils/AstEditor';
-import { isBrsFile, isDottedGetExpression, isLiteralString, isXmlFile } from '../astUtils/reflection';
-import { WalkMode, createVisitor } from '../astUtils/visitors';
-import type { BrsFile } from '../files/BrsFile';
-import type { XmlFile } from '../files/XmlFile';
-import type { NormalizedKeepRule } from '../BsConfig';
-import type { BscFile } from '../interfaces';
-import type { CallfuncExpression } from '../parser/Expression';
-import { ParseMode } from '../parser/Parser';
-import { EmptyStatement } from '../parser/Statement';
-import type { FunctionStatement } from '../parser/Statement';
-import type { Program } from '../Program';
-import util from '../util';
-import type { Logger } from '../logging';
+import type { AstEditor } from '../../astUtils/AstEditor';
+import { isBrsFile, isDottedGetExpression, isLiteralString, isXmlFile } from '../../astUtils/reflection';
+import { WalkMode, createVisitor } from '../../astUtils/visitors';
+import type { BrsFile } from '../../files/BrsFile';
+import type { XmlFile } from '../../files/XmlFile';
+import type { NormalizedKeepRule } from '../../BsConfig';
+import type { BscFile } from '../../interfaces';
+import type { CallfuncExpression } from '../../parser/Expression';
+import { ParseMode } from '../../parser/Parser';
+import { EmptyStatement } from '../../parser/Statement';
+import type { FunctionStatement } from '../../parser/Statement';
+import type { Program } from '../../Program';
+import util from '../../util';
+import type { Logger } from '../../logging';
 
 /**
  * Keep rule with patterns pre-compiled and src paths pre-resolved.

From 7672891ff882379e2071e549e3fa127021b7395a Mon Sep 17 00:00:00 2001
From: Tyler Smith <tyler@tksssoftware.com>
Date: Thu, 19 Mar 2026 13:26:18 -0300
Subject: [PATCH 35/44] remove whitespace

---
 src/Program.ts | 1 -
 1 file changed, 1 deletion(-)

diff --git a/src/Program.ts b/src/Program.ts
index 7cfbd3759..33158af17 100644
--- a/src/Program.ts
+++ b/src/Program.ts
@@ -1311,7 +1311,6 @@ export class Program {
         const astEditor = new AstEditor();
 
         this.plugins.emit('beforeProgramTranspile', this, entries, astEditor);
-
         return {
             entries: entries,
             getOutputPath: getOutputPath,

From 5986f59bfda9f357b3debfb3dc9a4092e2824190 Mon Sep 17 00:00:00 2001
From: Tyler Smith <tyler@tksssoftware.com>
Date: Thu, 19 Mar 2026 13:31:25 -0300
Subject: [PATCH 36/44] readme update

---
 docs/shaking.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/docs/shaking.md b/docs/shaking.md
index 2bd0393e5..d45dc9f72 100644
--- a/docs/shaking.md
+++ b/docs/shaking.md
@@ -167,6 +167,8 @@ The pattern is resolved relative to `rootDir` unless it is an absolute path.
 }
 ```
 
+When a `src` rule covers every function in a `.brs` file, the file is never put through the BrighterScript transpiler — it is copied verbatim to staging. This is important for third-party SDK files where transpilation could corrupt valid BrightScript (for example, a local variable that shares a name with a project namespace).
+
 #### `dest` — glob against the package-relative destination path
 
 Matches the path the file will have inside the deployed zip. BrighterScript source files (`.bs`) are matched using their transpiled extension (`.brs`), so always write `.brs` in dest patterns. An optional `pkg:/` prefix is accepted and stripped before matching.

From c4d231d5d966a515832dc97facda327f8053fa56 Mon Sep 17 00:00:00 2001
From: Tyler Smith <tyler@tksssoftware.com>
Date: Thu, 19 Mar 2026 13:37:52 -0300
Subject: [PATCH 37/44] omit fully protected files from transpiler

---
 src/bscPlugin/treeShaker/TreeShaker.spec.ts | 33 ++++++++++++++++++++-
 src/bscPlugin/treeShaker/TreeShaker.ts      | 14 +++++++++
 2 files changed, 46 insertions(+), 1 deletion(-)

diff --git a/src/bscPlugin/treeShaker/TreeShaker.spec.ts b/src/bscPlugin/treeShaker/TreeShaker.spec.ts
index 24b578914..e8f45a0e2 100644
--- a/src/bscPlugin/treeShaker/TreeShaker.spec.ts
+++ b/src/bscPlugin/treeShaker/TreeShaker.spec.ts
@@ -4,7 +4,7 @@ import { standardizePath as s } from '../../util';
 import * as fsExtra from 'fs-extra';
 import undent from 'undent';
 
-describe.only('TreeShaker', () => {
+describe('TreeShaker', () => {
     let program: Program;
     const tempDir = s`${__dirname}/../.tmp`;
     const rootDir = s`${tempDir}/rootDir`;
@@ -998,6 +998,37 @@ describe.only('TreeShaker', () => {
                 expect(vendorCode).to.include('sub anotherVendorFn()');
                 expect(mainCode).not.to.include('sub appHelper()');
             });
+
+            it('calls from within a src-kept .brs file still count towards keeping functions in other files', async () => {
+                // Even though BrazeSDK.brs is fully protected, its reference pass still runs.
+                // Calls it makes into other files must keep those callees alive.
+                program = new Program({
+                    rootDir: rootDir, stagingDir: stagingDir,
+                    treeShaking: { enabled: true, keep: [{ src: '**/SDK.brs' }] }
+                });
+                program.setFile('source/SDK.brs', `
+                    function Track() as void
+                        InternalHelper()
+                    end function
+                `);
+                program.setFile('source/helpers.bs', `
+                    sub internalHelper()
+                        print "called from SDK.brs"
+                    end sub
+
+                    sub unreachable()
+                        print "never called"
+                    end sub
+                `);
+                program.setFile('source/main.bs', `
+                    sub main()
+                    end sub
+                `);
+
+                const helpersCode = await getTranspiled('source/helpers.bs');
+                expect(helpersCode).to.include('sub internalHelper()');
+                expect(helpersCode).not.to.include('sub unreachable()');
+            });
         });
 
         describe('dest rule', () => {
diff --git a/src/bscPlugin/treeShaker/TreeShaker.ts b/src/bscPlugin/treeShaker/TreeShaker.ts
index eaee3c46c..d3bcd5101 100644
--- a/src/bscPlugin/treeShaker/TreeShaker.ts
+++ b/src/bscPlugin/treeShaker/TreeShaker.ts
@@ -85,6 +85,11 @@ export class TreeShaker {
     // in different files are tracked independently; shake() is a single Set lookup per statement
     private toRemove = new Set<FunctionStatement>();
 
+    // Files that have at least one function to remove — shake() skips files not in this set,
+    // guaranteeing needsTranspiled is never touched on fully-protected files (e.g. a .brs SDK
+    // covered entirely by a src keep rule)
+    private filesToShake = new Set<BrsFile>();
+
     // Resolved rootDir for src-path matching
     private rootDir = '';
 
@@ -105,6 +110,7 @@ export class TreeShaker {
         this.compiledRules = [];
         this.filePathCache.clear();
         this.toRemove.clear();
+        this.filesToShake.clear();
         this.rootDir = '';
         this.removalLog.clear();
     }
@@ -232,6 +238,7 @@ export class TreeShaker {
         for (const { bsName, brsName, stmt, file } of this.allStatements) {
             if (this.isUnused(bsName, brsName) && !this.isKept(brsName, file)) {
                 this.toRemove.add(stmt);
+                this.filesToShake.add(file);
             }
         }
     }
@@ -519,6 +526,13 @@ export class TreeShaker {
             return;
         }
 
+        // Skip files with nothing to remove — this guarantees needsTranspiled is never
+        // set on fully-protected files (e.g. a .brs SDK covered by a src keep rule),
+        // preventing the BrighterScript transpiler from running on them.
+        if (!this.filesToShake.has(file)) {
+            return;
+        }
+
         const removed: string[] = [];
 
         file.ast.walk(createVisitor({

From a9b0de532839d1751b42d310fb082d02513b9cb5 Mon Sep 17 00:00:00 2001
From: Tyler Smith <tyler@tksssoftware.com>
Date: Thu, 19 Mar 2026 13:45:49 -0300
Subject: [PATCH 38/44] Fix issue

---
 src/bscPlugin/treeShaker/TreeShaker.spec.ts | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/src/bscPlugin/treeShaker/TreeShaker.spec.ts b/src/bscPlugin/treeShaker/TreeShaker.spec.ts
index e8f45a0e2..625797d66 100644
--- a/src/bscPlugin/treeShaker/TreeShaker.spec.ts
+++ b/src/bscPlugin/treeShaker/TreeShaker.spec.ts
@@ -3,6 +3,8 @@ import { Program } from '../../Program';
 import { standardizePath as s } from '../../util';
 import * as fsExtra from 'fs-extra';
 import undent from 'undent';
+import { AstEditor } from '../../astUtils/AstEditor';
+import { TreeShaker } from './TreeShaker';
 
 describe('TreeShaker', () => {
     let program: Program;
@@ -927,7 +929,7 @@ describe('TreeShaker', () => {
         });
 
         describe('src rule', () => {
-            it('does not set needsTranspiled on a .brs file fully covered by a src keep rule', async () => {
+            it('does not set needsTranspiled on a .brs file fully covered by a src keep rule', () => {
                 // When every function in a .brs file is kept by a keep rule, shake() never
                 // replaces any statement, so needsTranspiled must stay false. This prevents
                 // the BrighterScript transpiler from running on the file and applying
@@ -953,10 +955,7 @@ describe('TreeShaker', () => {
                 `);
 
                 program.validate();
-                // Trigger the shake pass the same way Program.beforeProgramTranspile does
-                const { AstEditor } = require('../../astUtils/AstEditor');
                 const editor = new AstEditor();
-                const { TreeShaker } = require('./TreeShaker');
                 const shaker = new TreeShaker();
                 shaker.analyze(program, program.options.treeShaking.keep);
 

From e3717f1f71d5e08b0f5018456cbd10ba7e46c136 Mon Sep 17 00:00:00 2001
From: Tyler Smith <tyler@tksssoftware.com>
Date: Thu, 19 Mar 2026 18:07:26 -0300
Subject: [PATCH 39/44] pattern fix

---
 src/bscPlugin/treeShaker/TreeShaker.spec.ts | 36 ++++++++++++++++++++-
 src/bscPlugin/treeShaker/TreeShaker.ts      | 29 ++++++++++++-----
 2 files changed, 56 insertions(+), 9 deletions(-)

diff --git a/src/bscPlugin/treeShaker/TreeShaker.spec.ts b/src/bscPlugin/treeShaker/TreeShaker.spec.ts
index 625797d66..4cb284d1b 100644
--- a/src/bscPlugin/treeShaker/TreeShaker.spec.ts
+++ b/src/bscPlugin/treeShaker/TreeShaker.spec.ts
@@ -929,6 +929,40 @@ describe('TreeShaker', () => {
         });
 
         describe('src rule', () => {
+            it('matches a **/filename.brs pattern against a file whose srcPath is outside rootDir', () => {
+                // SomeSDK.brs lives in an sdks/ directory that is NOT under rootDir.
+                // The resolved pattern would be /rootDir/**/SomeSDK.brs which would NOT
+                // match /sdks/SomeVendor/source/SomeSDK.brs. The raw pattern **/SomeSDK.brs
+                // must be tried against the absolute srcPath directly.
+                const externalDir = s`${tempDir}/sdks/SomeVendor/source`;
+                fsExtra.ensureDirSync(externalDir);
+                const externalFile = s`${externalDir}/SomeSDK.brs`;
+                fsExtra.writeFileSync(externalFile, `
+                    function sdkTrack() as void
+                    end function
+                `);
+
+                program = new Program({
+                    rootDir: rootDir, stagingDir: stagingDir,
+                    treeShaking: { enabled: true, keep: [{ src: '**/SomeSDK.brs' }] }
+                });
+                program.setFile({ src: externalFile, dest: 'source/SomeSDK.brs' }, undefined);
+                program.setFile('source/main.bs', `
+                    sub main()
+                    end sub
+                `);
+
+                program.validate();
+                const editor = new AstEditor();
+                const shaker = new TreeShaker();
+                shaker.analyze(program, program.options.treeShaking.keep);
+
+                const sdkFile = program.getFile('source/SomeSDK.brs');
+                shaker.shake(sdkFile, editor);
+
+                expect((sdkFile as any).needsTranspiled).to.be.false;
+            });
+
             it('does not set needsTranspiled on a .brs file fully covered by a src keep rule', () => {
                 // When every function in a .brs file is kept by a keep rule, shake() never
                 // replaces any statement, so needsTranspiled must stay false. This prevents
@@ -999,7 +1033,7 @@ describe('TreeShaker', () => {
             });
 
             it('calls from within a src-kept .brs file still count towards keeping functions in other files', async () => {
-                // Even though BrazeSDK.brs is fully protected, its reference pass still runs.
+                // Even though SomeSDK.brs is fully protected, its reference pass still runs.
                 // Calls it makes into other files must keep those callees alive.
                 program = new Program({
                     rootDir: rootDir, stagingDir: stagingDir,
diff --git a/src/bscPlugin/treeShaker/TreeShaker.ts b/src/bscPlugin/treeShaker/TreeShaker.ts
index d3bcd5101..afb62c3d6 100644
--- a/src/bscPlugin/treeShaker/TreeShaker.ts
+++ b/src/bscPlugin/treeShaker/TreeShaker.ts
@@ -180,14 +180,27 @@ export class TreeShaker {
             }
 
             if (rule.src) {
-                compiled.srcMatchers = rule.src.map(pattern => {
-                    const resolved = path.isAbsolute(pattern)
-                        ? pattern
-                        : path.resolve(this.rootDir, pattern);
-                    // Normalize to forward slashes: util.standardizePath uses path.win32.normalize
-                    // which produces backslashes on Windows, and minimatch treats \ as an escape
-                    // character rather than a path separator unless paths are normalized first.
-                    return new minimatch.Minimatch(util.standardizePath(resolved).replace(/\\/g, '/'), { nocase: true });
+                // Each pattern is compiled into two matchers so both use-cases work:
+                //
+                //  1. Raw — pattern used as-is against the absolute srcPath.
+                //     e.g. "**/SDK.brs" stays "**/SDK.brs"
+                //     Matches files anywhere, including outside rootDir (vendored SDKs).
+                //
+                //  2. Resolved (absolute) — pattern resolved against rootDir.
+                //     e.g. "source/vendor/**" → "/rootDir/source/vendor/**"
+                //     Matches files that live inside rootDir using rootDir-relative paths.
+                //
+                // ruleMatches passes if either matcher hits, so both styles work correctly.
+                compiled.srcMatchers = rule.src.flatMap(pattern => {
+                    const normalized = pattern.replace(/\\/g, '/');
+                    const matchers: minimatch.Minimatch[] = [
+                        new minimatch.Minimatch(normalized, { nocase: true })
+                    ];
+                    if (!path.isAbsolute(pattern)) {
+                        const resolved = util.standardizePath(path.resolve(this.rootDir, pattern)).replace(/\\/g, '/');
+                        matchers.push(new minimatch.Minimatch(resolved, { nocase: true }));
+                    }
+                    return matchers;
                 });
             }
 

From 94f9c9d94fb1428a683dade691d81226520034b9 Mon Sep 17 00:00:00 2001
From: Tyler Smith <tyler@tksssoftware.com>
Date: Thu, 19 Mar 2026 18:28:32 -0300
Subject: [PATCH 40/44] treeShaking normalization tests

---
 src/util.spec.ts | 91 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 91 insertions(+)

diff --git a/src/util.spec.ts b/src/util.spec.ts
index 391bdd760..f0ce15687 100644
--- a/src/util.spec.ts
+++ b/src/util.spec.ts
@@ -431,6 +431,97 @@ describe('util', () => {
                 expect(util.normalizeConfig(<any>{ bslibDestinationDir: input }).bslibDestinationDir).to.equal('source/opt');
             });
         });
+
+        describe('treeShaking normalization', () => {
+            it('defaults to disabled with empty keep list when treeShaking is omitted', () => {
+                const result = util.normalizeConfig({}).treeShaking;
+                expect(result.enabled).to.be.false;
+                expect(result.keep).to.eql([]);
+            });
+
+            it('sets enabled to true when specified', () => {
+                const result = util.normalizeConfig({ treeShaking: { enabled: true } }).treeShaking;
+                expect(result.enabled).to.be.true;
+            });
+
+            it('expands a plain string entry to a functions rule', () => {
+                const result = util.normalizeConfig({
+                    treeShaking: { enabled: true, keep: ['MyHelper'] }
+                }).treeShaking;
+                expect(result.keep).to.eql([{ functions: ['myhelper'] }]);
+            });
+
+            it('lowercases function names from plain string entries', () => {
+                const result = util.normalizeConfig({
+                    treeShaking: { enabled: true, keep: ['MyNamespace_MyFunc'] }
+                }).treeShaking;
+                expect(result.keep[0].functions).to.eql(['mynamespace_myfunc']);
+            });
+
+            it('wraps a scalar src value in an array', () => {
+                const result = util.normalizeConfig({
+                    treeShaking: { enabled: true, keep: [{ src: 'source/lib.bs' }] }
+                }).treeShaking;
+                expect(result.keep[0].src).to.eql(['source/lib.bs']);
+            });
+
+            it('wraps a scalar dest value in an array', () => {
+                const result = util.normalizeConfig({
+                    treeShaking: { enabled: true, keep: [{ dest: 'source/lib.brs' }] }
+                }).treeShaking;
+                expect(result.keep[0].dest).to.eql(['source/lib.brs']);
+            });
+
+            it('wraps a scalar functions value in an array and lowercases it', () => {
+                const result = util.normalizeConfig({
+                    treeShaking: { enabled: true, keep: [{ functions: 'MyFunc' }] }
+                }).treeShaking;
+                expect(result.keep[0].functions).to.eql(['myfunc']);
+            });
+
+            it('wraps a scalar matches value in an array', () => {
+                const result = util.normalizeConfig({
+                    treeShaking: { enabled: true, keep: [{ matches: 'rodash_*' }] }
+                }).treeShaking;
+                expect(result.keep[0].matches).to.eql(['rodash_*']);
+            });
+
+            it('passes through already-array values unchanged', () => {
+                const result = util.normalizeConfig({
+                    treeShaking: { enabled: true, keep: [{ src: ['a.bs', 'b.bs'], functions: ['foo', 'bar'] }] }
+                }).treeShaking;
+                expect(result.keep[0].src).to.eql(['a.bs', 'b.bs']);
+                expect(result.keep[0].functions).to.eql(['foo', 'bar']);
+            });
+
+            it('silently skips object rules with no recognized fields', () => {
+                const result = util.normalizeConfig({
+                    treeShaking: { enabled: true, keep: [{} as any] }
+                }).treeShaking;
+                expect(result.keep).to.eql([]);
+            });
+
+            it('silently skips null and undefined entries in keep array', () => {
+                const result = util.normalizeConfig({
+                    treeShaking: { enabled: true, keep: [null as any, undefined as any] }
+                }).treeShaking;
+                expect(result.keep).to.eql([]);
+            });
+
+            it('handles a non-array keep value gracefully', () => {
+                const result = util.normalizeConfig({
+                    treeShaking: { enabled: true, keep: 'notAnArray' as any }
+                }).treeShaking;
+                expect(result.keep).to.eql([]);
+            });
+
+            it('re-normalizes treeShaking when the property is overwritten via assignment', () => {
+                const config = util.normalizeConfig({ treeShaking: { enabled: false } });
+                config.treeShaking = { enabled: true, keep: ['MyFunc'] } as any;
+                expect(config.treeShaking.enabled).to.be.true;
+                expect(config.treeShaking.keep).to.eql([{ functions: ['myfunc'] }]);
+            });
+        });
     });
 
     describe('areArraysEqual', () => {

From 8d6d302a3354a8b7b0cf793d1419bc0f322e83cd Mon Sep 17 00:00:00 2001
From: Tyler Smith <tyler@tksssoftware.com>
Date: Thu, 19 Mar 2026 18:31:54 -0300
Subject: [PATCH 41/44] changes map for any compiled rule that ends up with no
 criteria

---
 src/bscPlugin/treeShaker/TreeShaker.spec.ts | 31 +++++++++++++++++++++
 src/bscPlugin/treeShaker/TreeShaker.ts      | 13 +++++++--
 2 files changed, 42 insertions(+), 2 deletions(-)

diff --git a/src/bscPlugin/treeShaker/TreeShaker.spec.ts b/src/bscPlugin/treeShaker/TreeShaker.spec.ts
index 4cb284d1b..2a8626628 100644
--- a/src/bscPlugin/treeShaker/TreeShaker.spec.ts
+++ b/src/bscPlugin/treeShaker/TreeShaker.spec.ts
@@ -1416,6 +1416,37 @@ describe('TreeShaker', () => {
                 const code = await getTranspiled('source/main.bs');
                 expect(code).not.to.include('sub unused()');
             });
+
+            it('does not keep everything when a NormalizedKeepRule with no fields reaches compileRules', async () => {
+                // If an empty CompiledRule were allowed through, ruleMatches would return true
+                // for every function (all field checks short-circuit to pass when undefined),
+                // effectively disabling tree shaking entirely. compileRules must drop it.
+                const shaker = new TreeShaker();
+                // Bypass normalizeTreeShakingConfig by calling analyze with a pre-built
+                // NormalizedKeepRule that has no fields — simulates a caller that bypasses
+                // the normalizer or a future code path that produces an empty rule.
+                program = new Program({ rootDir: rootDir, stagingDir: stagingDir, treeShaking: { enabled: true } });
+                program.setFile('source/main.bs', `
+                    sub main()
+                    end sub
+
+                    sub unused()
+                        print "must still be removed"
+                    end sub
+                `);
+                program.validate();
+
+                // Pass an empty NormalizedKeepRule directly to analyze()
+                shaker.analyze(program, [{}] as any);
+
+                const editor = new AstEditor();
+                const mainFile = program.getFile('source/main.bs');
+                shaker.shake(mainFile, editor);
+
+                // The empty rule must have been dropped — unused() should be in toRemove
+                const code = await getTranspiled('source/main.bs');
+                expect(code).not.to.include('sub unused()');
+            });
         });
     });
 });
diff --git a/src/bscPlugin/treeShaker/TreeShaker.ts b/src/bscPlugin/treeShaker/TreeShaker.ts
index afb62c3d6..2a54bf9bc 100644
--- a/src/bscPlugin/treeShaker/TreeShaker.ts
+++ b/src/bscPlugin/treeShaker/TreeShaker.ts
@@ -166,7 +166,7 @@ export class TreeShaker {
      * - `src` patterns are resolved to absolute paths against rootDir up front.
      */
     private compileRules(rules: NormalizedKeepRule[]): CompiledRule[] {
-        return rules.map(rule => {
+        return rules.flatMap(rule => {
             const compiled: CompiledRule = {};
 
             if (rule.functions) {
@@ -213,7 +213,16 @@ export class TreeShaker {
                 });
             }
 
-            return compiled;
+            // Defensively skip rules with no criteria — an empty CompiledRule would cause
+            // ruleMatches to return true for every function (all field checks are skipped
+            // when undefined), effectively keeping everything and disabling tree shaking.
+            const hasAnyCriteria =
+                compiled.functionsSet !== undefined ||
+                compiled.matchesMatchers !== undefined ||
+                compiled.srcMatchers !== undefined ||
+                compiled.destMatchers !== undefined;
+
+            return hasAnyCriteria ? [compiled] : [];
         });
     }
 

From 84a4da200ed8a003e3110b6498c7452aee2f1e93 Mon Sep 17 00:00:00 2001
From: Tyler Smith <tyler@tksssoftware.com>
Date: Thu, 19 Mar 2026 18:39:15 -0300
Subject: [PATCH 42/44] readme update

---
 docs/shaking.md | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/docs/shaking.md b/docs/shaking.md
index d45dc9f72..5ef60d6c0 100644
--- a/docs/shaking.md
+++ b/docs/shaking.md
@@ -169,6 +169,14 @@ The pattern is resolved relative to `rootDir` unless it is an absolute path.
 
 When a `src` rule covers every function in a `.brs` file, the file is never put through the BrighterScript transpiler — it is copied verbatim to staging. This is important for third-party SDK files where transpilation could corrupt valid BrightScript (for example, a local variable that shares a name with a project namespace).
 
+> **Known limitation — namespace/variable name collision in `.brs` files**
+>
+> If your project defines a namespace whose name matches a local variable in a `.brs` file, BrighterScript's transpiler will incorrectly rewrite method calls on that variable as namespace function calls. For example, if the project has `namespace date` and a `.brs` file contains `date = CreateObject("roDateTime")`, the transpiler turns `date.AsSeconds()` into `date_AsSeconds()`, which crashes at runtime because no such global function exists.
+>
+> This only affects `.brs` files that are put through the transpiler. The recommended workarounds are:
+> - **Rename the local variable** in the `.brs` file to avoid the collision (e.g. `dateObj = CreateObject("roDateTime")`).
+> - **Protect the entire `.brs` file** with a `src` keep rule (e.g. `{ "src": "**/ThirdPartySDK.brs" }`). When all functions in a `.brs` file are kept, the tree shaker skips it entirely and the transpiler is never invoked on it.
+
 #### `dest` — glob against the package-relative destination path
 
 Matches the path the file will have inside the deployed zip. BrighterScript source files (`.bs`) are matched using their transpiled extension (`.brs`), so always write `.brs` in dest patterns. An optional `pkg:/` prefix is accepted and stripped before matching.

From ac3d832dbae055d8c82f70534c0181b61fbbd038 Mon Sep 17 00:00:00 2001
From: Tyler Smith <tyler@tksssoftware.com>
Date: Fri, 20 Mar 2026 08:17:01 -0300
Subject: [PATCH 43/44] customizations support

---
 src/bscPlugin/treeShaker/TreeShaker.spec.ts | 33 +++++++++++++++++++++
 src/bscPlugin/treeShaker/TreeShaker.ts      | 18 +++++++++++
 2 files changed, 51 insertions(+)

diff --git a/src/bscPlugin/treeShaker/TreeShaker.spec.ts b/src/bscPlugin/treeShaker/TreeShaker.spec.ts
index 2a8626628..975cb975b 100644
--- a/src/bscPlugin/treeShaker/TreeShaker.spec.ts
+++ b/src/bscPlugin/treeShaker/TreeShaker.spec.ts
@@ -772,6 +772,39 @@ describe('TreeShaker', () => {
             expect(code).to.include('sub onContentChanged()');
             expect(code).not.to.include('sub unused()');
         });
+
+        it('preserves functions referenced in XML customization handler attributes (Instant Resume)', async () => {
+            program.setFile('components/MainScene.xml', undent`
+                <?xml version="1.0" encoding="utf-8" ?>
+                <component name="MainScene" extends="Scene">
+                    <customization suspendhandler="onApplicationSuspend" />
+                    <customization resumehandler="onApplicationResume" />
+                    <script type="text/brightscript" uri="MainScene.bs"/>
+                    <children>
+                    </children>
+                </component>
+            `);
+            program.setFile('components/MainScene.bs', `
+                sub init()
+                end sub
+
+                sub onApplicationSuspend()
+                    print "suspend"
+                end sub
+
+                sub onApplicationResume()
+                    print "resume"
+                end sub
+
+                sub unused()
+                end sub
+            `);
+
+            const code = await getTranspiled('components/MainScene.bs');
+            expect(code).to.include('sub onApplicationSuspend()');
+            expect(code).to.include('sub onApplicationResume()');
+            expect(code).not.to.include('sub unused()');
+        });
     });
 
     describe('treeShaking.keep rules', () => {
diff --git a/src/bscPlugin/treeShaker/TreeShaker.ts b/src/bscPlugin/treeShaker/TreeShaker.ts
index 2a54bf9bc..0364f7545 100644
--- a/src/bscPlugin/treeShaker/TreeShaker.ts
+++ b/src/bscPlugin/treeShaker/TreeShaker.ts
@@ -340,6 +340,24 @@ export class TreeShaker {
         // Collect onChange="callbackName" attribute values from any element in the
         // component <children> tree (e.g. inline node definitions with onChange set).
         this.collectXmlOnChangeCallbacks(component?.children);
+
+        // Collect handler function names from <customization> elements.
+        // Roku Instant Resume uses attributes like suspendhandler="onApplicationSuspend"
+        // and resumehandler="onApplicationResume" outside the <children> tree, so they
+        // are invisible to collectXmlOnChangeCallbacks.
+        if (Array.isArray(component?.customizations)) {
+            for (const node of component.customizations) {
+                if (Array.isArray(node?.attributes)) {
+                    for (const attr of node.attributes) {
+                        const key: string | undefined = attr?.key?.text;
+                        const value: string | undefined = attr?.value?.text;
+                        if (key?.toLowerCase().endsWith('handler') && value && /^[a-z_][a-z0-9_.]*$/i.test(value)) {
+                            this.xmlInterfaceFunctions.add(value.toLowerCase());
+                        }
+                    }
+                }
+            }
+        }
     }
 
     private collectXmlOnChangeCallbacks(children: any) {

From 41bcae30b61148d1086138d776dcea4a6ace0f35 Mon Sep 17 00:00:00 2001
From: Tyler Smith <tyler@tksssoftware.com>
Date: Fri, 20 Mar 2026 08:43:26 -0300
Subject: [PATCH 44/44] test for function passed by reference as an argument to
 another function

---
 src/bscPlugin/treeShaker/TreeShaker.spec.ts | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/src/bscPlugin/treeShaker/TreeShaker.spec.ts b/src/bscPlugin/treeShaker/TreeShaker.spec.ts
index 975cb975b..865ffeb00 100644
--- a/src/bscPlugin/treeShaker/TreeShaker.spec.ts
+++ b/src/bscPlugin/treeShaker/TreeShaker.spec.ts
@@ -455,6 +455,25 @@ describe('TreeShaker', () => {
             expect(code).not.to.include('sub unused()');
         });
 
+        it('preserves a function passed by reference as an argument to another function', async () => {
+            program.setFile('source/main.bs', `
+                sub init()
+                    setHandler(mySub1)
+                end sub
+
+                sub mySub1()
+                    print "hey"
+                end sub
+
+                sub unused()
+                end sub
+            `);
+
+            const code = await getTranspiled('source/main.bs');
+            expect(code).to.include('sub mySub1()');
+            expect(code).not.to.include('sub unused()');
+        });
+
         it('preserves functions called via @. callfunc shorthand', async () => {
             program.setFile('source/main.bs', `
                 sub init()