#14386

Committed 09 May 2025 11:44AM UTC coverage: 87.026% (-2.0%) from 89.017%

Build Type

push

Committed by

Commit Message

Merge a194c3925 into 489231ac7

Coverage Stats

13731 of 16677 branches covered (82.33%)

Branch coverage included in aggregate %.

8175 of 8874 new or added lines in 103 files covered. (92.12%)

85 existing lines in 22 files now uncovered.

14603 of 15881 relevant lines covered (91.95%)

20322.22 hits per line

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

89.0

/src/parser/BrightScriptDocParser.ts

import type { GetSymbolTypeOptions } from '../SymbolTable';
import util from '../util';
import type { AstNode, Expression } from './AstNode';
import type { Location } from 'vscode-languageserver';
import { Parser } from './Parser';
import type { ExpressionStatement } from './Statement';
import { isExpressionStatement } from '../astUtils/reflection';
import { SymbolTypeFlag } from '../SymbolTypeFlag';
import type { Token } from '../lexer/Token';

const tagRegex = /@(\w+)(?:\s+(.*))?/;
const paramRegex = /(?:{([^}]*)}\s+)?(?:(\[?\w+\]?))\s*(.*)/;
const returnRegex = /(?:{([^}]*)})?\s*(.*)/;
const typeTagRegex = /(?:{([^}]*)})?/;

export enum BrsDocTagKind {
    Description = 'description',
    Param = 'param',
    Return = 'return',
    Type = 'type'
}

export class BrightScriptDocParser {

    public parseNode(node: AstNode) {
        const commentTokens: Token[] = [];
        const result = this.parse(
            util.getNodeDocumentation(node, {
                prettyPrint: false,
                commentTokens: commentTokens
            }),
            commentTokens);
        for (const tag of result.tags) {
            if ((tag as BrsDocWithType).typeExpression) {
                (tag as BrsDocWithType).typeExpression.symbolTable = node.getSymbolTable();
            }
        }
        return result;
    }

    public parse(documentation: string, matchingTokens: Token[] = []) {
        const brsDoc = new BrightScriptDoc(documentation);
        if (!documentation) {
            return brsDoc;
        }
        const lines = documentation.split('\n');
        const blockLines = [] as { line: string; token?: Token }[];
        const descriptionLines = [] as { line: string; token?: Token }[];
        let lastTag: BrsDocTag;
        let haveMatchingTokens = false;
        if (lines.length === matchingTokens.length) {
            // We locations for each line, so we can add Locations
            haveMatchingTokens = true;
        }
        function augmentLastTagWithBlockLines() {
            if (blockLines.length > 0 && lastTag) {
                // add to the description or details to previous tag
                if (typeof (lastTag as BrsDocWithDescription).description !== 'undefined') {
                    (lastTag as BrsDocWithDescription).description += '\n' + blockLines.map(obj => obj.line).join('\n');
                    (lastTag as BrsDocWithDescription).description = (lastTag as BrsDocWithDescription).description.trim();
                }
                if (typeof lastTag.detail !== 'undefined') {
                    lastTag.detail += '\n' + blockLines.map(obj => obj.line).join('\n');
                    lastTag.detail = lastTag.detail.trim();
                }
                if (haveMatchingTokens) {
                    lastTag.location = util.createBoundingLocation(lastTag.location, blockLines[blockLines.length - 1].token.location);
                }
            }
            blockLines.length = 0;
        }
        for (let line of lines) {
            let token = haveMatchingTokens ? matchingTokens.shift() : undefined;
            line = line.trim();
            while (line.startsWith('\'')) {
                // remove leading apostrophes
                line = line.substring(1).trim();
            }
            if (!line.startsWith('@')) {
                if (lastTag) {

                    blockLines.push({ line: line, token: token });
                } else if (descriptionLines.length > 0 || line) {
                    // add a line to the list if it's not empty
                    descriptionLines.push({ line: line, token: token });
                }
            } else {
                augmentLastTagWithBlockLines();
                const newTag = this.parseLine(line, token);
                lastTag = newTag;
                if (newTag) {
                    brsDoc.tags.push(newTag);
                }
            }
        }
        augmentLastTagWithBlockLines();
        brsDoc.description = descriptionLines.map(obj => obj.line).join('\n').trim();
        return brsDoc;
    }

    public getTypeLocationFromToken(token: Token): Location {
        if (!token?.location) {
            return undefined;
        }
        const startCurly = token.text.indexOf('{');
        const endCurly = token.text.indexOf('}');
        if (startCurly === -1 || endCurly === -1 || endCurly <= startCurly) {
            return undefined;
        }
        return {
            uri: token.location.uri,
            range: {
                start: {
                    line: token.location.range.start.line,
                    character: token.location.range.start.character + startCurly + 1
                },
                end: {
                    line: token.location.range.start.line,
                    character: token.location.range.start.character + endCurly
                }
            }
        };
    }

    private parseLine(line: string, token?: Token) {
        line = line.trim();
        const match = tagRegex.exec(line);
        if (!match) {
            return;
        }
        const tagName = match[1];
        const detail = match[2] ?? '';

        let result: BrsDocTag = {
            tagName: tagName,
            detail: detail
        };

        switch (tagName) {
            case BrsDocTagKind.Param:
                result = this.parseParam(detail);
                break;
            case BrsDocTagKind.Return:
            case 'returns':
                result = this.parseReturn(detail);
                break;
            case BrsDocTagKind.Type:
                result = this.parseType(detail);
                break;
        }
        return {
            ...result,
            token: token,
            location: token?.location
        };
    }

    private parseParam(detail: string): BrsDocParamTag {
        let type = '';
        let description = '';
        let optional = false;
        let paramName = '';
        let match = paramRegex.exec(detail);
        if (match) {
            type = match[1] ?? '';
            paramName = match[2] ?? '';
            description = match[3] ?? '';
        } else {
            paramName = detail.trim();
        }
        if (paramName) {
            optional = paramName.startsWith('[') && paramName.endsWith(']');
            paramName = paramName.replace(/\[|\]/g, '').trim();
        }
        return {
            tagName: BrsDocTagKind.Param,
            name: paramName,
            typeString: type,
            typeExpression: this.getTypeExpressionFromTypeString(type),
            description: description,
            optional: optional,
            detail: detail
        };
    }

    private parseReturn(detail: string): BrsDocWithDescription {
        let match = returnRegex.exec(detail);
        let type = '';
        let description = '';
        if (match) {
            type = match[1] ?? '';
            description = match[2] ?? '';
        }
        return {
            tagName: BrsDocTagKind.Return,
            typeString: type,
            typeExpression: this.getTypeExpressionFromTypeString(type),
            description: description,
            detail: detail
        };
    }

    private parseType(detail: string): BrsDocWithType {
        let match = typeTagRegex.exec(detail);
        let type = '';
        if (match) {
            if (match[1]) {
                type = match[1] ?? '';
            }
        }
        return {
            tagName: BrsDocTagKind.Type,
            typeString: type,
            typeExpression: this.getTypeExpressionFromTypeString(type),
            detail: detail
        };
    }

    private getTypeExpressionFromTypeString(typeString: string) {
        if (!typeString) {
            return undefined;
        }
        let result: Expression;
        try {
            let { ast } = Parser.parse(typeString);
            if (isExpressionStatement(ast?.statements?.[0])) {
                result = (ast.statements[0] as ExpressionStatement).expression;
            }
        } catch (e) {
            //ignore
        }
        return result;
    }
}

export class BrightScriptDoc {

    protected _description: string;

    public tags = [] as BrsDocTag[];

    constructor(
        public readonly documentation: string
    ) {
    }

    set description(value: string) {
        this._description = value;
    }

    get description() {
        const descTag = this.tags.find((tag) => {
            return tag.tagName === BrsDocTagKind.Description;
        });

        let result = this._description ?? '';
        if (descTag) {
            const descTagDetail = descTag.detail;
            result = result ? result + '\n' + descTagDetail : descTagDetail;
        }
        return result.trim();
    }

    getParam(name: string) {
        const lowerName = name.toLowerCase();
        return this.tags.find((tag) => {
            return tag.tagName === BrsDocTagKind.Param && (tag as BrsDocParamTag).name.toLowerCase() === lowerName;
        }) as BrsDocParamTag;
    }

    getReturn() {
        return this.tags.find((tag) => {
            return tag.tagName === BrsDocTagKind.Return || tag.tagName === 'returns';
        }) as BrsDocWithDescription;
    }

    getTypeTag() {
        return this.tags.find((tag) => {
            return tag.tagName === BrsDocTagKind.Type;
        }) as BrsDocWithType;
    }

    getTypeTagByName(name: string) {
        const lowerName = name.toLowerCase();
        return this.tags.find((tag) => {
            return tag.tagName === BrsDocTagKind.Type && (tag as BrsDocParamTag).name.toLowerCase() === lowerName;
        }) as BrsDocWithType;
    }

    getTag(tagName: string) {
        return this.tags.find((tag) => {
            return tag.tagName === tagName;
        });
    }

    getAllTags(tagName: string) {
        return this.tags.filter((tag) => {
            return tag.tagName === tagName;
        });
    }

    getParamBscType(name: string, options: GetSymbolTypeOptions = { flags: SymbolTypeFlag.typetime }) {
        const param = this.getParam(name);
        return param?.typeExpression?.getType({ ...options, flags: SymbolTypeFlag.typetime });
    }

    getReturnBscType(options: GetSymbolTypeOptions = { flags: SymbolTypeFlag.typetime }) {
        const retTag = this.getReturn();
        return retTag?.typeExpression?.getType({ ...options, flags: SymbolTypeFlag.typetime });
    }

    getTypeTagBscType(options: GetSymbolTypeOptions = { flags: SymbolTypeFlag.typetime }) {
        const typeTag = this.getTypeTag();
        return typeTag?.typeExpression?.getType({ ...options, flags: SymbolTypeFlag.typetime });
    }
}

export interface BrsDocTag {
    tagName: string;
    detail?: string;
    location?: Location;
    token?: Token;
}
export interface BrsDocWithType extends BrsDocTag {
    typeString?: string;
    typeExpression?: Expression;
}

export interface BrsDocWithDescription extends BrsDocWithType {
    description?: string;
}

export interface BrsDocParamTag extends BrsDocWithDescription {
    name: string;
    optional?: boolean;
}

export let brsDocParser = new BrightScriptDocParser();
export default brsDocParser;

1	import type { GetSymbolTypeOptions } from '../SymbolTable';
2	import util from '../util';	1✔
3	import type { AstNode, Expression } from './AstNode';
4	import type { Location } from 'vscode-languageserver';
5	import { Parser } from './Parser';	1✔
6	import type { ExpressionStatement } from './Statement';
7	import { isExpressionStatement } from '../astUtils/reflection';	1✔
8	import { SymbolTypeFlag } from '../SymbolTypeFlag';	1✔
9	import type { Token } from '../lexer/Token';
10
11	const tagRegex = /@(\w+)(?:\s+(.*))?/;	1✔
12	const paramRegex = /(?:{([^}])}\s+)?(?:(\[?\w+\]?))\s(.*)/;	1✔
13	const returnRegex = /(?:{([^}])})?\s(.*)/;	1✔
14	const typeTagRegex = /(?:{([^}]*)})?/;	1✔
15
16	export enum BrsDocTagKind {	1✔
17	Description = 'description',	1✔
18	Param = 'param',	1✔
19	Return = 'return',	1✔
20	Type = 'type'	1✔
21	}
22
23	export class BrightScriptDocParser {	1✔
24
25	public parseNode(node: AstNode) {
26	const commentTokens: Token[] = [];	34,233✔
27	const result = this.parse(	34,233✔
28	util.getNodeDocumentation(node, {
29	prettyPrint: false,
30	commentTokens: commentTokens
31	}),
32	commentTokens);
33	for (const tag of result.tags) {	34,233✔
34	if ((tag as BrsDocWithType).typeExpression) {	300✔
35	(tag as BrsDocWithType).typeExpression.symbolTable = node.getSymbolTable();	273✔
36	}
37	}
38	return result;	34,233✔
39	}
40
41	public parse(documentation: string, matchingTokens: Token[] = []) {	17✔
42	const brsDoc = new BrightScriptDoc(documentation);	34,250✔
43	if (!documentation) {	34,250✔
44	return brsDoc;	33,323✔
45	}
46	const lines = documentation.split('\n');	927✔
47	const blockLines = [] as { line: string; token?: Token }[];	927✔
48	const descriptionLines = [] as { line: string; token?: Token }[];	927✔
49	let lastTag: BrsDocTag;
50	let haveMatchingTokens = false;	927✔
51	if (lines.length === matchingTokens.length) {	927✔
52	// We locations for each line, so we can add Locations
53	haveMatchingTokens = true;	910✔
54	}
55	function augmentLastTagWithBlockLines() {
56	if (blockLines.length > 0 && lastTag) {	1,250✔
57	// add to the description or details to previous tag
58	if (typeof (lastTag as BrsDocWithDescription).description !== 'undefined') {	17✔
59	(lastTag as BrsDocWithDescription).description += '\n' + blockLines.map(obj => obj.line).join('\n');	13✔
60	(lastTag as BrsDocWithDescription).description = (lastTag as BrsDocWithDescription).description.trim();	10✔
61	}
62	if (typeof lastTag.detail !== 'undefined') {	17!
63	lastTag.detail += '\n' + blockLines.map(obj => obj.line).join('\n');	21✔
64	lastTag.detail = lastTag.detail.trim();	17✔
65	}
66	if (haveMatchingTokens) {	17!
NEW 67	lastTag.location = util.createBoundingLocation(lastTag.location, blockLines[blockLines.length - 1].token.location);	×
68	}
69	}
70	blockLines.length = 0;	1,250✔
71	}
72	for (let line of lines) {	927✔
73	let token = haveMatchingTokens ? matchingTokens.shift() : undefined;	1,087✔
74	line = line.trim();	1,087✔
75	while (line.startsWith('\'')) {	1,087✔
76	// remove leading apostrophes
77	line = line.substring(1).trim();	2✔
78	}
79	if (!line.startsWith('@')) {	1,087✔
80	if (lastTag) {	764✔
81
82	blockLines.push({ line: line, token: token });	21✔
83	} else if (descriptionLines.length > 0 \|\| line) {	743✔
84	// add a line to the list if it's not empty
85	descriptionLines.push({ line: line, token: token });	727✔
86	}
87	} else {
88	augmentLastTagWithBlockLines();	323✔
89	const newTag = this.parseLine(line, token);	323✔
90	lastTag = newTag;	323✔
91	if (newTag) {	323!
92	brsDoc.tags.push(newTag);	323✔
93	}
94	}
95	}
96	augmentLastTagWithBlockLines();	927✔
97	brsDoc.description = descriptionLines.map(obj => obj.line).join('\n').trim();	927✔
98	return brsDoc;	927✔
99	}
100
101	public getTypeLocationFromToken(token: Token): Location {
102	if (!token?.location) {	15!
NEW 103	return undefined;	×
104	}
105	const startCurly = token.text.indexOf('{');	15✔
106	const endCurly = token.text.indexOf('}');	15✔
107	if (startCurly === -1 \|\| endCurly === -1 \|\| endCurly <= startCurly) {	15✔
108	return undefined;	6✔
109	}
110	return {	9✔
111	uri: token.location.uri,
112	range: {
113	start: {
114	line: token.location.range.start.line,
115	character: token.location.range.start.character + startCurly + 1
116	},
117	end: {
118	line: token.location.range.start.line,
119	character: token.location.range.start.character + endCurly
120	}
121	}
122	};
123	}
124
125	private parseLine(line: string, token?: Token) {
126	line = line.trim();	323✔
127	const match = tagRegex.exec(line);	323✔
128	if (!match) {	323!
NEW 129	return;	×
130	}
131	const tagName = match[1];	323✔
132	const detail = match[2] ?? '';	323✔
133
134	let result: BrsDocTag = {	323✔
135	tagName: tagName,
136	detail: detail
137	};
138
139	switch (tagName) {	323✔
140	case BrsDocTagKind.Param:	393✔
141	result = this.parseParam(detail);	200✔
142	break;	200✔
143	case BrsDocTagKind.Return:
144	case 'returns':
145	result = this.parseReturn(detail);	84✔
146	break;	84✔
147	case BrsDocTagKind.Type:
148	result = this.parseType(detail);	26✔
149	break;	26✔
150	}
151	return {	323✔
152	...result,
153	token: token,
154	location: token?.location	969✔
155	};
156	}
157
158	private parseParam(detail: string): BrsDocParamTag {
159	let type = '';	200✔
160	let description = '';	200✔
161	let optional = false;	200✔
162	let paramName = '';	200✔
163	let match = paramRegex.exec(detail);	200✔
164	if (match) {	200!
165	type = match[1] ?? '';	200✔
166	paramName = match[2] ?? '';	200!
167	description = match[3] ?? '';	200!
168	} else {
NEW 169	paramName = detail.trim();	×
170	}
171	if (paramName) {	200!
172	optional = paramName.startsWith('[') && paramName.endsWith(']');	200✔
173	paramName = paramName.replace(/\[\|\]/g, '').trim();	200✔
174	}
175	return {	200✔
176	tagName: BrsDocTagKind.Param,
177	name: paramName,
178	typeString: type,
179	typeExpression: this.getTypeExpressionFromTypeString(type),
180	description: description,
181	optional: optional,
182	detail: detail
183	};
184	}
185
186	private parseReturn(detail: string): BrsDocWithDescription {
187	let match = returnRegex.exec(detail);	84✔
188	let type = '';	84✔
189	let description = '';	84✔
190	if (match) {	84!
191	type = match[1] ?? '';	84✔
192	description = match[2] ?? '';	84!
193	}
194	return {	84✔
195	tagName: BrsDocTagKind.Return,
196	typeString: type,
197	typeExpression: this.getTypeExpressionFromTypeString(type),
198	description: description,
199	detail: detail
200	};
201	}
202
203	private parseType(detail: string): BrsDocWithType {
204	let match = typeTagRegex.exec(detail);	26✔
205	let type = '';	26✔
206	if (match) {	26!
207	if (match[1]) {	26!
208	type = match[1] ?? '';	26!
209	}
210	}
211	return {	26✔
212	tagName: BrsDocTagKind.Type,
213	typeString: type,
214	typeExpression: this.getTypeExpressionFromTypeString(type),
215	detail: detail
216	};
217	}
218
219	private getTypeExpressionFromTypeString(typeString: string) {
220	if (!typeString) {	310✔
221	return undefined;	26✔
222	}
223	let result: Expression;
224	try {	284✔
225	let { ast } = Parser.parse(typeString);	284✔
226	if (isExpressionStatement(ast?.statements?.[0])) {	284!
227	result = (ast.statements[0] as ExpressionStatement).expression;	284✔
228	}
229	} catch (e) {
230	//ignore
231	}
232	return result;	284✔
233	}
234	}
235
236	export class BrightScriptDoc {	1✔
237
238	protected _description: string;
239
240	public tags = [] as BrsDocTag[];	34,250✔
241
242	constructor(
243	public readonly documentation: string	34,250✔
244	) {
245	}
246
247	set description(value: string) {
248	this._description = value;	927✔
249	}
250
251	get description() {
252	const descTag = this.tags.find((tag) => {	11✔
253	return tag.tagName === BrsDocTagKind.Description;	16✔
254	});
255
256	let result = this._description ?? '';	11!
257	if (descTag) {	11✔
258	const descTagDetail = descTag.detail;	2✔
259	result = result ? result + '\n' + descTagDetail : descTagDetail;	2!
260	}
261	return result.trim();	11✔
262	}
263
264	getParam(name: string) {
265	const lowerName = name.toLowerCase();	5,947✔
266	return this.tags.find((tag) => {	5,947✔
267	return tag.tagName === BrsDocTagKind.Param && (tag as BrsDocParamTag).name.toLowerCase() === lowerName;	214✔
268	}) as BrsDocParamTag;
269	}
270
271	getReturn() {
272	return this.tags.find((tag) => {	4,678✔
273	return tag.tagName === BrsDocTagKind.Return \|\| tag.tagName === 'returns';	96✔
274	}) as BrsDocWithDescription;
275	}
276
277	getTypeTag() {
278	return this.tags.find((tag) => {	1,526✔
279	return tag.tagName === BrsDocTagKind.Type;	10✔
280	}) as BrsDocWithType;
281	}
282
283	getTypeTagByName(name: string) {
NEW 284	const lowerName = name.toLowerCase();	×
NEW 285	return this.tags.find((tag) => {	×
NEW 286	return tag.tagName === BrsDocTagKind.Type && (tag as BrsDocParamTag).name.toLowerCase() === lowerName;	×
287	}) as BrsDocWithType;
288	}
289
290	getTag(tagName: string) {
291	return this.tags.find((tag) => {	3✔
292	return tag.tagName === tagName;	3✔
293	});
294	}
295
296	getAllTags(tagName: string) {
297	return this.tags.filter((tag) => {	6✔
298	return tag.tagName === tagName;	23✔
299	});
300	}
301
302	getParamBscType(name: string, options: GetSymbolTypeOptions = { flags: SymbolTypeFlag.typetime }) {	×
303	const param = this.getParam(name);	5,919✔
304	return param?.typeExpression?.getType({ ...options, flags: SymbolTypeFlag.typetime });	5,919✔
305	}
306
307	getReturnBscType(options: GetSymbolTypeOptions = { flags: SymbolTypeFlag.typetime }) {	×
308	const retTag = this.getReturn();	4,663✔
309	return retTag?.typeExpression?.getType({ ...options, flags: SymbolTypeFlag.typetime });	4,663✔
310	}
311
312	getTypeTagBscType(options: GetSymbolTypeOptions = { flags: SymbolTypeFlag.typetime }) {	×
313	const typeTag = this.getTypeTag();	1,524✔
314	return typeTag?.typeExpression?.getType({ ...options, flags: SymbolTypeFlag.typetime });	1,524✔
315	}
316	}
317
318	export interface BrsDocTag {
319	tagName: string;
320	detail?: string;
321	location?: Location;
322	token?: Token;
323	}
324	export interface BrsDocWithType extends BrsDocTag {
325	typeString?: string;
326	typeExpression?: Expression;
327	}
328
329	export interface BrsDocWithDescription extends BrsDocWithType {
330	description?: string;
331	}
332
333	export interface BrsDocParamTag extends BrsDocWithDescription {
334	name: string;
335	optional?: boolean;
336	}
337
338	export let brsDocParser = new BrightScriptDocParser();	1✔
339	export default brsDocParser;	1✔

rokucommunity / brighterscript / #14386

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