#15685

Committed 29 Apr 2026 02:04PM UTC coverage: 89.084% (+0.08%) from 89.009%

Build Type

push

Committed by

Commit Message

Share per-file namespace data via lazy ScopeNamespaceLookup view (#1684)

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

Coverage Stats

8353 of 9876 branches covered (84.58%)

Branch coverage included in aggregate %.

176 of 180 new or added lines in 4 files covered. (97.78%)

1 existing line in 1 file now uncovered.

10604 of 11404 relevant lines covered (92.98%)

2048.42 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

91.89

/src/ScopeNamespaceLookup.ts

import type { BrsFile } from './files/BrsFile';
import type { Scope, NamespaceContainer, NamespaceFileContribution } from './Scope';
import { isBrsFile } from './astUtils/reflection';

/**
 * The per-scope namespace lookup. Implements `Map<string, NamespaceContainer>` so existing
 * plugin and internal consumers (which iterate, `.get`, `.has`, `.size`, etc.) keep working.
 *
 * Internally lazy: `get(name)` builds the container for that name only, by intersecting
 * the program-level `(name -> contributing files)` map with the scope's file set.
 *
 * Sharing primitives:
 *  - When exactly one in-scope file contributes to a namespace (the dominant case under
 *    a typical build), the container's heavy fields point directly at the file's pre-built
 *    `NamespaceFileContribution` data — including its symbolTable. Two scopes pulling in
 *    the same file get containers wrapping the same inner data.
 *  - When multiple in-scope files contribute, the container is built per-scope by merging
 *    contributions. This path is rare in practice but must be correct: it covers cases
 *    where a namespace is split across files that are all in the same scope (e.g. a shared
 *    declaration file plus theme-specific extensions).
 *
 * Iteration (`keys` / `values` / `entries` / `forEach`) populates every container, since
 * "give me everything" callers don't benefit from laziness. This matches the cost of the
 * pre-Phase-4 `buildNamespaceLookup` and only fires from LSP completion paths.
 */
export class ScopeNamespaceLookup extends Map<string, NamespaceContainer> {
    constructor(private readonly scope: Scope) {
        super();
    }

    /**
     * Lower-cased name parts contributed by any file in scope. Built once per lookup
     * instance, used as the "does this namespace exist in scope" oracle for `has` and
     * for driving iteration.
     */
    private nameSet: Set<string> | undefined;
    /** Map from lower-cased parent name to lower-cased immediate child names. */
    private childrenByParent: Map<string, string[]> | undefined;
    /** Cached `Set<BrsFile>` for `scope.getAllFiles()`, used when filtering contributors. */
    private inScopeBrsFiles: Set<BrsFile> | undefined;
    /** Set to true after `populateAll` runs so iteration doesn't keep re-checking. */
    private isFullyBuilt = false;

    private ensureNameIndex() {
        if (this.nameSet) {
            return;
        }
        const nameSet = new Set<string>();
        const childrenByParent = new Map<string, string[]>();
        for (const file of this.scope.getAllFiles()) {
            if (isBrsFile(file)) {
                // eslint-disable-next-line @typescript-eslint/dot-notation
                for (const nameLower of file['getNamespaceContributions']().keys()) {
                    nameSet.add(nameLower);
                }
            }
        }
        for (const name of nameSet) {
            const lastDot = name.lastIndexOf('.');
            if (lastDot > 0) {
                const parentLower = name.substring(0, lastDot);
                let arr = childrenByParent.get(parentLower);
                if (!arr) {
                    arr = [];
                    childrenByParent.set(parentLower, arr);
                }
                arr.push(name);
            }
        }
        this.nameSet = nameSet;
        this.childrenByParent = childrenByParent;
    }

    private getInScopeBrsFiles(): Set<BrsFile> {
        if (!this.inScopeBrsFiles) {
            const set = new Set<BrsFile>();
            for (const file of this.scope.getAllFiles()) {
                if (isBrsFile(file)) {
                    set.add(file);
                }
            }
            this.inScopeBrsFiles = set;
        }
        return this.inScopeBrsFiles;
    }

    public override has(key: string): boolean {
        const lower = key?.toLowerCase();
        if (!lower) {
            return false;
        }
        if (super.has(lower)) {
            return super.get(lower) !== undefined;
        }
        this.ensureNameIndex();
        return this.nameSet!.has(lower);
    }

    public override get(key: string): NamespaceContainer | undefined {
        const lower = key?.toLowerCase();
        if (!lower) {
            return undefined;
        }
        if (super.has(lower)) {
            return super.get(lower);
        }
        this.ensureNameIndex();
        if (!this.nameSet!.has(lower)) {
            //memoize the negative result so repeated misses are cheap
            super.set(lower, undefined as any);
            return undefined;
        }
        const container = this.buildContainer(lower);
        super.set(lower, container as any);
        return container;
    }

    public override get size(): number {
        this.ensureNameIndex();
        return this.nameSet!.size;
    }

    public override keys(): IterableIterator<string> {
        this.populateAll();
        return super.keys();
    }

    public override values(): IterableIterator<NamespaceContainer> {
        this.populateAll();
        return super.values();
    }

    public override entries(): IterableIterator<[string, NamespaceContainer]> {
        this.populateAll();
        return super.entries();
    }

    public override [Symbol.iterator](): IterableIterator<[string, NamespaceContainer]> {
        return this.entries();
    }

    public override forEach(
        callback: (value: NamespaceContainer, key: string, map: Map<string, NamespaceContainer>) => void,
        thisArg?: any
    ): void {
        this.populateAll();
        super.forEach(callback, thisArg);
    }

    private populateAll() {
        if (this.isFullyBuilt) {
            return;
        }
        this.ensureNameIndex();
        for (const name of this.nameSet!) {
            this.get(name);
        }
        //drop entries memoized as undefined so iteration only visits real containers
        for (const [key, value] of [...super.entries()]) {
            if (value === undefined) {
                super.delete(key);
            }
        }
        this.isFullyBuilt = true;
    }

    private buildContainer(nameLower: string): NamespaceContainer | undefined {
        // eslint-disable-next-line @typescript-eslint/dot-notation
        const candidateFiles = this.scope.program['getNamespaceContributors'](nameLower);
        if (!candidateFiles || candidateFiles.size === 0) {
            return undefined;
        }
        const inScopeFiles = this.getInScopeBrsFiles();
        const inScopeContributions: NamespaceFileContribution[] = [];
        for (const file of candidateFiles) {
            if (inScopeFiles.has(file)) {
                // eslint-disable-next-line @typescript-eslint/dot-notation
                const contribution = file['getNamespaceContributions']().get(nameLower);
                if (contribution) {
                    inScopeContributions.push(contribution);
                }
            }
        }
        if (inScopeContributions.length === 0) {
            return undefined;
        }
        if (inScopeContributions.length === 1) {
            return this.wrapSingleContribution(inScopeContributions[0], nameLower);
        }
        return this.aggregateContributions(inScopeContributions, nameLower);
    }

    /**
     * Fast path: single in-scope contributor. The wrapper is per-scope (so its
     * `namespaces` field can hold scope-specific children), but every other field
     * points directly at the contribution's pre-built data.
     */
    private wrapSingleContribution(contribution: NamespaceFileContribution, nameLower: string): NamespaceContainer {
        //field order matches the NamespaceContainer interface declaration so the
        //fast-path and slow-path containers share a single V8 hidden class.
        return {
            file: contribution.file,
            fullName: contribution.fullName,
            nameRange: contribution.nameRange,
            lastPartName: contribution.lastPartName,
            namespaces: this.buildScopedChildren(nameLower),
            statements: contribution.statements,
            classStatements: contribution.classStatements,
            functionStatements: contribution.functionStatements,
            enumStatements: contribution.enumStatements,
            constStatements: contribution.constStatements,
            symbolTable: contribution.symbolTable
        };
    }

    /**
     * Slow path: multiple in-scope contributors. The merged statement collections and
     * symbolTable live at the program level (`Program.getAggregateNamespaceContainer`),
     * keyed by `(nameLower, sorted-contributor-pkgPaths)`. Two scopes with the same
     * in-scope file set for this namespace share the same aggregate object, just like
     * the fast path shares the per-file contribution.
     *
     * The wrapper container itself is per-scope so its `namespaces` (children) field can
     * reflect the querying scope's file set.
     */
    private aggregateContributions(contributions: NamespaceFileContribution[], nameLower: string): NamespaceContainer {
        // eslint-disable-next-line @typescript-eslint/dot-notation
        const aggregate = this.scope.program['getAggregateNamespaceContainer'](nameLower, contributions);
        //field order matches the NamespaceContainer interface declaration so fast-path
        //and slow-path containers share a single V8 hidden class
        return {
            file: aggregate.file,
            fullName: aggregate.fullName,
            nameRange: aggregate.nameRange,
            lastPartName: aggregate.lastPartName,
            namespaces: this.buildScopedChildren(nameLower),
            statements: aggregate.statements,
            classStatements: aggregate.classStatements,
            functionStatements: aggregate.functionStatements,
            enumStatements: aggregate.enumStatements,
            constStatements: aggregate.constStatements,
            symbolTable: aggregate.symbolTable
        };
    }

    /**
     * Build the scope-filtered children map for a parent namespace. Walks the
     * pre-computed `childrenByParent` index and recursively materializes each
     * in-scope child container.
     */
    private buildScopedChildren(parentNameLower: string): Map<string, NamespaceContainer> {
        const children = new Map<string, NamespaceContainer>();
        this.ensureNameIndex();
        const childNames = this.childrenByParent!.get(parentNameLower);
        if (!childNames) {
            return children;
        }
        for (const childName of childNames) {
            const child = this.get(childName);
            if (child) {
                children.set(child.lastPartName.toLowerCase(), child);
            }
        }
        return children;
    }
}

1	import type { BrsFile } from './files/BrsFile';
2	import type { Scope, NamespaceContainer, NamespaceFileContribution } from './Scope';
3	import { isBrsFile } from './astUtils/reflection';	1✔
4
5	/**
6	* The per-scope namespace lookup. Implements `Map<string, NamespaceContainer>` so existing
7	* plugin and internal consumers (which iterate, `.get`, `.has`, `.size`, etc.) keep working.
8	*
9	* Internally lazy: `get(name)` builds the container for that name only, by intersecting
10	* the program-level `(name -> contributing files)` map with the scope's file set.
11	*
12	* Sharing primitives:
13	* - When exactly one in-scope file contributes to a namespace (the dominant case under
14	* a typical build), the container's heavy fields point directly at the file's pre-built
15	* `NamespaceFileContribution` data — including its symbolTable. Two scopes pulling in
16	* the same file get containers wrapping the same inner data.
17	* - When multiple in-scope files contribute, the container is built per-scope by merging
18	* contributions. This path is rare in practice but must be correct: it covers cases
19	* where a namespace is split across files that are all in the same scope (e.g. a shared
20	* declaration file plus theme-specific extensions).
21	*
22	* Iteration (`keys` / `values` / `entries` / `forEach`) populates every container, since
23	* "give me everything" callers don't benefit from laziness. This matches the cost of the
24	* pre-Phase-4 `buildNamespaceLookup` and only fires from LSP completion paths.
25	*/
26	export class ScopeNamespaceLookup extends Map<string, NamespaceContainer> {	1✔
27	constructor(private readonly scope: Scope) {	676✔
28	super();	676✔
29	}
30
31	/**
32	* Lower-cased name parts contributed by any file in scope. Built once per lookup
33	* instance, used as the "does this namespace exist in scope" oracle for `has` and
34	* for driving iteration.
35	*/
36	private nameSet: Set<string> \| undefined;
37	/** Map from lower-cased parent name to lower-cased immediate child names. */
38	private childrenByParent: Map<string, string[]> \| undefined;
39	/** Cached `Set<BrsFile>` for `scope.getAllFiles()`, used when filtering contributors. */
40	private inScopeBrsFiles: Set<BrsFile> \| undefined;
41	/** Set to true after `populateAll` runs so iteration doesn't keep re-checking. */
42	private isFullyBuilt = false;	676✔
43
44	private ensureNameIndex() {
45	if (this.nameSet) {	2,288✔
46	return;	1,614✔
47	}
48	const nameSet = new Set<string>();	674✔
49	const childrenByParent = new Map<string, string[]>();	674✔
50	for (const file of this.scope.getAllFiles()) {	674✔
51	if (isBrsFile(file)) {	854✔
52	// eslint-disable-next-line @typescript-eslint/dot-notation
53	for (const nameLower of file['getNamespaceContributions']().keys()) {	784✔
54	nameSet.add(nameLower);	422✔
55	}
56	}
57	}
58	for (const name of nameSet) {	674✔
59	const lastDot = name.lastIndexOf('.');	379✔
60	if (lastDot > 0) {	379✔
61	const parentLower = name.substring(0, lastDot);	133✔
62	let arr = childrenByParent.get(parentLower);	133✔
63	if (!arr) {	133✔
64	arr = [];	123✔
65	childrenByParent.set(parentLower, arr);	123✔
66	}
67	arr.push(name);	133✔
68	}
69	}
70	this.nameSet = nameSet;	674✔
71	this.childrenByParent = childrenByParent;	674✔
72	}
73
74	private getInScopeBrsFiles(): Set<BrsFile> {
75	if (!this.inScopeBrsFiles) {	332✔
76	const set = new Set<BrsFile>();	224✔
77	for (const file of this.scope.getAllFiles()) {	224✔
78	if (isBrsFile(file)) {	314✔
79	set.add(file);	291✔
80	}
81	}
82	this.inScopeBrsFiles = set;	224✔
83	}
84	return this.inScopeBrsFiles;	332✔
85	}
86
87	public override has(key: string): boolean {
88	const lower = key?.toLowerCase();	113!
89	if (!lower) {	113!
NEW 90	return false;	×
91	}
92	if (super.has(lower)) {	113✔
93	return super.get(lower) !== undefined;	99✔
94	}
95	this.ensureNameIndex();	14✔
96	return this.nameSet!.has(lower);	14✔
97	}
98
99	public override get(key: string): NamespaceContainer \| undefined {
100	const lower = key?.toLowerCase();	3,455!
101	if (!lower) {	3,455!
NEW 102	return undefined;	×
103	}
104	if (super.has(lower)) {	3,455✔
105	return super.get(lower);	1,537✔
106	}
107	this.ensureNameIndex();	1,918✔
108	if (!this.nameSet!.has(lower)) {	1,918✔
109	//memoize the negative result so repeated misses are cheap
110	super.set(lower, undefined as any);	1,586✔
111	return undefined;	1,586✔
112	}
113	const container = this.buildContainer(lower);	332✔
114	super.set(lower, container as any);	332✔
115	return container;	332✔
116	}
117
118	public override get size(): number {
119	this.ensureNameIndex();	1✔
120	return this.nameSet!.size;	1✔
121	}
122
123	public override keys(): IterableIterator<string> {
124	this.populateAll();	2✔
125	return super.keys();	2✔
126	}
127
128	public override values(): IterableIterator<NamespaceContainer> {
129	this.populateAll();	1✔
130	return super.values();	1✔
131	}
132
133	public override entries(): IterableIterator<[string, NamespaceContainer]> {
134	this.populateAll();	34✔
135	return super.entries();	34✔
136	}
137
138	public override [Symbol.iterator](): IterableIterator<[string, NamespaceContainer]> {
139	return this.entries();	33✔
140	}
141
142	public override forEach(
143	callback: (value: NamespaceContainer, key: string, map: Map<string, NamespaceContainer>) => void,
144	thisArg?: any
145	): void {
146	this.populateAll();	1✔
147	super.forEach(callback, thisArg);	1✔
148	}
149
150	private populateAll() {
151	if (this.isFullyBuilt) {	38✔
152	return;	15✔
153	}
154	this.ensureNameIndex();	23✔
155	for (const name of this.nameSet!) {	23✔
156	this.get(name);	45✔
157	}
158	//drop entries memoized as undefined so iteration only visits real containers
159	for (const [key, value] of [...super.entries()]) {	23✔
160	if (value === undefined) {	52✔
161	super.delete(key);	7✔
162	}
163	}
164	this.isFullyBuilt = true;	23✔
165	}
166
167	private buildContainer(nameLower: string): NamespaceContainer \| undefined {
168	// eslint-disable-next-line @typescript-eslint/dot-notation
169	const candidateFiles = this.scope.program['getNamespaceContributors'](nameLower);	332✔
170	if (!candidateFiles \|\| candidateFiles.size === 0) {	332!
NEW 171	return undefined;	×
172	}
173	const inScopeFiles = this.getInScopeBrsFiles();	332✔
174	const inScopeContributions: NamespaceFileContribution[] = [];	332✔
175	for (const file of candidateFiles) {	332✔
176	if (inScopeFiles.has(file)) {	374✔
177	// eslint-disable-next-line @typescript-eslint/dot-notation
178	const contribution = file['getNamespaceContributions']().get(nameLower);	368✔
179	if (contribution) {	368!
180	inScopeContributions.push(contribution);	368✔
181	}
182	}
183	}
184	if (inScopeContributions.length === 0) {	332!
NEW 185	return undefined;	×
186	}
187	if (inScopeContributions.length === 1) {	332✔
188	return this.wrapSingleContribution(inScopeContributions[0], nameLower);	299✔
189	}
190	return this.aggregateContributions(inScopeContributions, nameLower);	33✔
191	}
192
193	/**
194	* Fast path: single in-scope contributor. The wrapper is per-scope (so its
195	* `namespaces` field can hold scope-specific children), but every other field
196	* points directly at the contribution's pre-built data.
197	*/
198	private wrapSingleContribution(contribution: NamespaceFileContribution, nameLower: string): NamespaceContainer {
199	//field order matches the NamespaceContainer interface declaration so the
200	//fast-path and slow-path containers share a single V8 hidden class.
201	return {	299✔
202	file: contribution.file,
203	fullName: contribution.fullName,
204	nameRange: contribution.nameRange,
205	lastPartName: contribution.lastPartName,
206	namespaces: this.buildScopedChildren(nameLower),
207	statements: contribution.statements,
208	classStatements: contribution.classStatements,
209	functionStatements: contribution.functionStatements,
210	enumStatements: contribution.enumStatements,
211	constStatements: contribution.constStatements,
212	symbolTable: contribution.symbolTable
213	};
214	}
215
216	/**
217	* Slow path: multiple in-scope contributors. The merged statement collections and
218	* symbolTable live at the program level (`Program.getAggregateNamespaceContainer`),
219	* keyed by `(nameLower, sorted-contributor-pkgPaths)`. Two scopes with the same
220	* in-scope file set for this namespace share the same aggregate object, just like
221	* the fast path shares the per-file contribution.
222	*
223	* The wrapper container itself is per-scope so its `namespaces` (children) field can
224	* reflect the querying scope's file set.
225	*/
226	private aggregateContributions(contributions: NamespaceFileContribution[], nameLower: string): NamespaceContainer {
227	// eslint-disable-next-line @typescript-eslint/dot-notation
228	const aggregate = this.scope.program['getAggregateNamespaceContainer'](nameLower, contributions);	33✔
229	//field order matches the NamespaceContainer interface declaration so fast-path
230	//and slow-path containers share a single V8 hidden class
231	return {	33✔
232	file: aggregate.file,
233	fullName: aggregate.fullName,
234	nameRange: aggregate.nameRange,
235	lastPartName: aggregate.lastPartName,
236	namespaces: this.buildScopedChildren(nameLower),
237	statements: aggregate.statements,
238	classStatements: aggregate.classStatements,
239	functionStatements: aggregate.functionStatements,
240	enumStatements: aggregate.enumStatements,
241	constStatements: aggregate.constStatements,
242	symbolTable: aggregate.symbolTable
243	};
244	}
245
246	/**
247	* Build the scope-filtered children map for a parent namespace. Walks the
248	* pre-computed `childrenByParent` index and recursively materializes each
249	* in-scope child container.
250	*/
251	private buildScopedChildren(parentNameLower: string): Map<string, NamespaceContainer> {
252	const children = new Map<string, NamespaceContainer>();	332✔
253	this.ensureNameIndex();	332✔
254	const childNames = this.childrenByParent!.get(parentNameLower);	332✔
255	if (!childNames) {	332✔
256	return children;	250✔
257	}
258	for (const childName of childNames) {	82✔
259	const child = this.get(childName);	90✔
260	if (child) {	90!
261	children.set(child.lastPartName.toLowerCase(), child);	90✔
262	}
263	}
264	return children;	82✔
265	}
266	}

rokucommunity / brighterscript / #15685

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous