#15035

Committed 15 Dec 2025 08:42PM UTC coverage: 86.889%. Remained the same

Build Type

push

Committed by

Commit Message

Merge a60226157 into 2ea4d2108

Run Details

14466 of 17575 branches covered (82.31%)

Branch coverage included in aggregate %.

113 of 217 new or added lines in 8 files covered. (52.07%)

116 existing lines in 6 files now uncovered.

15185 of 16550 relevant lines covered (91.75%)

24075.2 hits per line

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

87.91

/src/util.ts

import * as fs from 'fs';
import * as fsExtra from 'fs-extra';
import type { ParseError } from 'jsonc-parser';
import { parse as parseJsonc, printParseErrorCode } from 'jsonc-parser';
import * as path from 'path';
import { rokuDeploy, DefaultFiles } from 'roku-deploy';
import type { Diagnostic, Position, DiagnosticRelatedInformation } from 'vscode-languageserver';
import { Range, Location } from 'vscode-languageserver';
import { URI } from 'vscode-uri';
import type { BsConfig, FinalizedBsConfig } from './BsConfig';
import { DiagnosticMessages } from './DiagnosticMessages';
import type { CallableContainer, BsDiagnostic, FileReference, CallableContainerMap, Plugin, ExpressionInfo, TranspileResult, MaybePromise, DisposableLike, ExtraSymbolData, GetTypeOptions, TypeChainProcessResult, PluginFactory, TypeCircularReferenceInfo } from './interfaces';
import { TypeChainEntry } from './interfaces';
import { BooleanType } from './types/BooleanType';
import { DoubleType } from './types/DoubleType';
import { DynamicType } from './types/DynamicType';
import { FloatType } from './types/FloatType';
import { IntegerType } from './types/IntegerType';
import { LongIntegerType } from './types/LongIntegerType';
import { ObjectType } from './types/ObjectType';
import { StringType } from './types/StringType';
import { VoidType } from './types/VoidType';
import { ParseMode } from './parser/Parser';
import type { CallExpression, CallfuncExpression, DottedGetExpression, FunctionParameterExpression, IndexedGetExpression, LiteralExpression, TypeExpression, VariableExpression } from './parser/Expression';
import { LogLevel, createLogger } from './logging';
import { isToken, type Identifier, type Token } from './lexer/Token';
import { TokenKind } from './lexer/TokenKind';
import { isAnyReferenceType, isBinaryExpression, isBooleanTypeLike, isBrsFile, isCallExpression, isCallableType, isCallfuncExpression, isClassType, isComponentType, isDottedGetExpression, isDoubleTypeLike, isDynamicType, isEnumMemberType, isExpression, isFloatTypeLike, isIndexedGetExpression, isIntegerTypeLike, isIntersectionType, isInvalidTypeLike, isLiteralString, isLongIntegerTypeLike, isNamespaceStatement, isNamespaceType, isNewExpression, isNumberTypeLike, isObjectType, isPrimitiveType, isReferenceType, isStatement, isStringTypeLike, isTypeExpression, isTypedArrayExpression, isTypedFunctionType, isUninitializedType, isUnionType, isVariableExpression, isVoidType, isXmlAttributeGetExpression, isXmlFile } from './astUtils/reflection';
import { WalkMode } from './astUtils/visitors';
import { SourceNode } from 'source-map';
import * as requireRelative from 'require-relative';
import type { BrsFile } from './files/BrsFile';
import type { XmlFile } from './files/XmlFile';
import type { AstNode, Expression, Statement } from './parser/AstNode';
import { AstNodeKind } from './parser/AstNode';
import type { UnresolvedSymbol } from './AstValidationSegmenter';
import type { BscSymbol, GetSymbolTypeOptions, SymbolTable } from './SymbolTable';
import { SymbolTypeFlag } from './SymbolTypeFlag';
import { createIdentifier, createToken } from './astUtils/creators';
import { MAX_RELATED_INFOS_COUNT } from './diagnosticUtils';
import type { BscType } from './types/BscType';
import { UnionType, unionTypeFactory } from './types/UnionType';
import { ArrayType } from './types/ArrayType';
import { BinaryOperatorReferenceType, TypePropertyReferenceType, ParamTypeFromValueReferenceType } from './types/ReferenceType';
import { AssociativeArrayType } from './types/AssociativeArrayType';
import { ComponentType } from './types/ComponentType';
import { FunctionType } from './types/FunctionType';
import type { AssignmentStatement, NamespaceStatement } from './parser/Statement';
import type { BscFile } from './files/BscFile';
import type { NamespaceType } from './types/NamespaceType';
import { getUniqueType } from './types/helpers';
import { InvalidType } from './types/InvalidType';
import { TypedFunctionType } from './types';
import { IntersectionType } from './types/IntersectionType';

export class Util {
    public clearConsole() {
        // process.stdout.write('\x1Bc');
    }

    /**
     * Get the version of brighterscript
     */
    public getBrighterScriptVersion() {
        try {
            return fsExtra.readJsonSync(`${__dirname}/../package.json`).version;
        } catch {
            return undefined;
        }
    }

    /**
     * Returns the number of parent directories in the filPath
     */
    public getParentDirectoryCount(filePath: string | undefined) {
        if (!filePath) {
            return -1;
        } else {
            return filePath.replace(/^pkg:/, '').split(/[\\\/]/).length - 1;
        }
    }

    /**
     * Determine if the file exists
     */
    public async pathExists(filePath: string | undefined) {
        if (!filePath) {
            return false;
        } else {
            return fsExtra.pathExists(filePath);
        }
    }

    /**
     * Determine if the file exists
     */
    public pathExistsSync(filePath: string | undefined) {
        if (!filePath) {
            return false;
        } else {
            return fsExtra.pathExistsSync(filePath);
        }
    }

    /**
     * Determine if this path is a directory
     */
    public isDirectorySync(dirPath: string | undefined) {
        try {
            return dirPath !== undefined && fs.existsSync(dirPath) && fs.lstatSync(dirPath).isDirectory();
        } catch (e) {
            return false;
        }
    }

    /**
     * Read a file from disk. If a failure occurrs, simply return undefined
     * @param filePath path to the file
     * @returns the string contents, or undefined if the file doesn't exist
     */
    public readFileSync(filePath: string): Buffer | undefined {
        try {
            return fsExtra.readFileSync(filePath);
        } catch (e) {
            return undefined;
        }
    }

    /**
     * Given a pkg path of any kind, transform it to a roku-specific pkg path (i.e. "pkg:/some/path.brs")
     */
    public sanitizePkgPath(pkgPath: string) {
        //convert all slashes to forwardslash
        pkgPath = pkgPath.replace(/[\/\\]+/g, '/');
        //ensure every path has the leading pkg:/
        return 'pkg:/' + pkgPath.replace(/^pkg:\//i, '');
    }

    /**
     * Find the path to the config file.
     * If the config file path doesn't exist
     * @param cwd the current working directory where the search for configs should begin
     */
    public getConfigFilePath(cwd?: string) {
        cwd = cwd ?? process.cwd();
        let configPath = path.join(cwd, 'bsconfig.json');
        //find the nearest config file path
        for (let i = 0; i < 100; i++) {
            if (this.pathExistsSync(configPath)) {
                return configPath;
            } else {
                let parentDirPath = path.dirname(path.dirname(configPath));
                configPath = path.join(parentDirPath, 'bsconfig.json');
            }
        }
    }

    public getRangeFromOffsetLength(text: string, offset: number, length: number) {
        let lineIndex = 0;
        let colIndex = 0;
        for (let i = 0; i < text.length; i++) {
            if (offset === i) {
                break;
            }
            let char = text[i];
            if (char === '\n' || (char === '\r' && text[i + 1] === '\n')) {
                lineIndex++;
                colIndex = 0;
                i++;
                continue;
            } else {
                colIndex++;
            }
        }
        return util.createRange(lineIndex, colIndex, lineIndex, colIndex + length);
    }

    /**
     * Load the contents of a config file.
     * If the file extends another config, this will load the base config as well.
     * @param configFilePath the relative or absolute path to a brighterscript config json file
     * @param parentProjectPaths a list of parent config files. This is used by this method to recursively build the config list
     */
    public loadConfigFile(configFilePath: string | undefined, parentProjectPaths?: string[], cwd = process.cwd()): BsConfig | undefined {
        if (configFilePath) {
            //if the config file path starts with question mark, then it's optional. return undefined if it doesn't exist
            if (configFilePath.startsWith('?')) {
                //remove leading question mark
                configFilePath = configFilePath.substring(1);
                if (fsExtra.pathExistsSync(path.resolve(cwd, configFilePath)) === false) {
                    return undefined;
                }
            }
            //keep track of the inheritance chain
            parentProjectPaths = parentProjectPaths ? parentProjectPaths : [];
            configFilePath = path.resolve(cwd, configFilePath);
            if (parentProjectPaths?.includes(configFilePath)) {
                parentProjectPaths.push(configFilePath);
                parentProjectPaths.reverse();
                throw new Error('Circular dependency detected: "' + parentProjectPaths.join('" => ') + '"');
            }
            //load the project file
            let projectFileContents = fsExtra.readFileSync(configFilePath).toString();
            let parseErrors = [] as ParseError[];
            let projectConfig = parseJsonc(projectFileContents, parseErrors, {
                allowEmptyContent: true,
                allowTrailingComma: true,
                disallowComments: false
            }) as BsConfig ?? {};
            if (parseErrors.length > 0) {
                let err = parseErrors[0];
                let diagnostic = {
                    ...DiagnosticMessages.syntaxError(`Syntax errors in bsconfig.json: ${printParseErrorCode(parseErrors[0].error)}`),
                    location: {
                        uri: this.pathToUri(configFilePath),
                        range: this.getRangeFromOffsetLength(projectFileContents, err.offset, err.length)
                    }
                } as BsDiagnostic;
                throw diagnostic; //eslint-disable-line @typescript-eslint/no-throw-literal
            }

            let projectFileCwd = path.dirname(configFilePath);

            //`plugins` paths should be relative to the current bsconfig
            this.resolvePathsRelativeTo(projectConfig, 'plugins', projectFileCwd);

            //`require` paths should be relative to cwd
            util.resolvePathsRelativeTo(projectConfig, 'require', projectFileCwd);

            let result: BsConfig;
            //if the project has a base file, load it
            if (projectConfig && typeof projectConfig.extends === 'string') {
                let baseProjectConfig = this.loadConfigFile(projectConfig.extends, [...parentProjectPaths, configFilePath], projectFileCwd);
                //extend the base config with the current project settings
                result = { ...baseProjectConfig, ...projectConfig };
            } else {
                result = projectConfig;
                let ancestors = parentProjectPaths ? parentProjectPaths : [];
                ancestors.push(configFilePath);
                (result as any)._ancestors = parentProjectPaths;
            }

            //make any paths in the config absolute (relative to the CURRENT config file)
            if (result.rootDir) {
                result.rootDir = path.resolve(projectFileCwd, result.rootDir);
            }
            if (result.outDir) {
                result.outDir = path.resolve(projectFileCwd, result.outDir);
            }
            if (result.cwd) {
                result.cwd = path.resolve(projectFileCwd, result.cwd);
            }
            if (result.sourceRoot && result.resolveSourceRoot) {
                result.sourceRoot = path.resolve(projectFileCwd, result.sourceRoot);
            }
            return result;
        }
    }

    /**
     * Convert relative paths to absolute paths, relative to the given directory. Also de-dupes the paths. Modifies the array in-place
     * @param collection usually a bsconfig.
     * @param key a key of the config to read paths from (usually this is `'plugins'` or `'require'`)
     * @param relativeDir the path to the folder where the paths should be resolved relative to. This should be an absolute path
     */
    public resolvePathsRelativeTo(collection: any, key: string, relativeDir: string) {
        if (!collection[key]) {
            return;
        }
        const result = new Set<string>();
        for (const p of collection[key] as string[] ?? []) {
            if (p) {
                result.add(
                    p?.startsWith('.') ? path.resolve(relativeDir, p) : p
                );
            }
        }
        collection[key] = [...result];
    }

    /**
     * Given a BsConfig object, start with defaults,
     * merge with bsconfig.json and the provided options.
     * @param config a bsconfig object to use as the baseline for the resulting config
     */
    public normalizeAndResolveConfig(config: BsConfig | undefined): FinalizedBsConfig {
        let result = this.normalizeConfig({});

        if (config?.noProject) {
            return result;
        }

        //if no options were provided, try to find a bsconfig.json file
        if (!config || !config.project) {
            result.project = this.getConfigFilePath(config?.cwd);
        } else {
            //use the config's project link
            result.project = config.project;
        }
        if (result.project) {
            let configFile = this.loadConfigFile(result.project, undefined, config?.cwd);
            result = Object.assign(result, configFile);
        }
        //override the defaults with the specified options
        result = Object.assign(result, config);
        return result;
    }

    /**
     * Set defaults for any missing items
     * @param config a bsconfig object to use as the baseline for the resulting config
     */
    public normalizeConfig(config: BsConfig | undefined): FinalizedBsConfig {
        config = config ?? {} as BsConfig;

        const cwd = config.cwd ?? process.cwd();

        let logLevel: LogLevel = LogLevel.log;

        if (typeof config.logLevel === 'string') {
            logLevel = LogLevel[(config.logLevel as string).toLowerCase()] ?? LogLevel.log;
        }

        let bslibDestinationDir = config.bslibDestinationDir ?? 'source';
        if (bslibDestinationDir !== 'source') {
            // strip leading and trailing slashes
            bslibDestinationDir = bslibDestinationDir.replace(/^(\/*)(.*?)(\/*)$/, '$2');
        }

        let noEmit: boolean;
        if ('noEmit' in config) {
            noEmit = config.noEmit;
        } else if ('copyToStaging' in config) {
            noEmit = !(config as any).copyToStaging; //invert the old value
        } else {
            noEmit = false; //default case
        }

        let outDir: string;
        if ('outDir' in config) {
            outDir = config.outDir ?? './out';
        } else if ('stagingFolderPath' in config) {
            outDir = (config as any).stagingFolderPath as string;
        } else if ('stagingDir' in config) {
            outDir = (config as any).stagingDir as string;
        } else {
            outDir = './out'; //default case
        }

        const configWithDefaults: Omit<FinalizedBsConfig, 'rootDir'> = {
            cwd: cwd,
            //use default files array from rokuDeploy
            files: config.files ?? [...DefaultFiles],
            outDir: outDir,
            sourceMap: config.sourceMap === true,
            watch: config.watch === true ? true : false,
            emitFullPaths: config.emitFullPaths === true ? true : false,
            noEmit: noEmit,
            ignoreErrorCodes: config.ignoreErrorCodes ?? [],
            diagnosticSeverityOverrides: config.diagnosticSeverityOverrides ?? {},
            diagnosticFilters: config.diagnosticFilters ?? [],
            diagnosticFiltersV0Compatibility: config.diagnosticFiltersV0Compatibility === true ? true : false,
            plugins: config.plugins ?? [],
            pruneEmptyCodeFiles: config.pruneEmptyCodeFiles === true ? true : false,
            autoImportComponentScript: config.autoImportComponentScript === true ? true : false,
            showDiagnosticsInConsole: config.showDiagnosticsInConsole === false ? false : true,
            sourceRoot: config.sourceRoot ? standardizePath(config.sourceRoot) : undefined,
            resolveSourceRoot: config.resolveSourceRoot === true ? true : false,
            allowBrighterScriptInBrightScript: config.allowBrighterScriptInBrightScript === true ? true : false,
            emitDefinitions: config.emitDefinitions === true ? true : false,
            removeParameterTypes: config.removeParameterTypes === true ? true : false,
            logLevel: logLevel,
            bslibDestinationDir: bslibDestinationDir,
            legacyCallfuncHandling: config.legacyCallfuncHandling === true ? true : false
        };

        //mutate `config` in case anyone is holding a reference to the incomplete one
        const merged: FinalizedBsConfig = Object.assign(config, configWithDefaults);

        return merged;
    }

    /**
     * Get the root directory from options.
     * Falls back to options.cwd.
     * Falls back to process.cwd
     * @param options a bsconfig object
     */
    public getRootDir(options: BsConfig) {
        if (!options) {
            throw new Error('Options is required');
        }
        let cwd = options.cwd;
        cwd = cwd ? cwd : process.cwd();
        let rootDir = options.rootDir ? options.rootDir : cwd;

        rootDir = path.resolve(cwd, rootDir);

        return rootDir;
    }

    /**
     * Given a list of callables as a dictionary indexed by their full name (namespace included, transpiled to underscore-separated.
     */
    public getCallableContainersByLowerName(callables: CallableContainer[]): CallableContainerMap {
        //find duplicate functions
        const result = new Map<string, CallableContainer[]>();

        for (let callableContainer of callables) {
            let lowerName = callableContainer.callable.getName(ParseMode.BrightScript).toLowerCase();

            //create a new array for this name
            const list = result.get(lowerName);
            if (list) {
                list.push(callableContainer);
            } else {
                result.set(lowerName, [callableContainer]);
            }
        }
        return result;
    }

    /**
     * Given an absolute path to a source file, and a target path,
     * compute the pkg path for the target relative to the source file's location
     */
    public getPkgPathFromTarget(containingFilePathAbsolute: string, targetPath: string) {
        // https://regex101.com/r/w7CG2N/1
        const regexp = /^(?:pkg|libpkg):(\/)?/i;
        const [fullScheme, slash] = regexp.exec(targetPath) ?? [];
        //if the target starts with 'pkg:' or 'libpkg:' then it's an absolute path. Return as is
        if (slash) {
            targetPath = targetPath.substring(fullScheme.length);
            if (targetPath === '') {
                return null;
            } else {
                return path.normalize(targetPath);
            }
        }
        //if the path is exactly `pkg:` or `libpkg:`
        if (targetPath === fullScheme && !slash) {
            return null;
        }

        //remove the filename
        let containingFolder = path.normalize(path.dirname(containingFilePathAbsolute));
        //start with the containing folder, split by slash
        let result = containingFolder.split(path.sep);

        //split on slash
        let targetParts = path.normalize(targetPath).split(path.sep);

        for (let part of targetParts) {
            if (part === '' || part === '.') {
                //do nothing, it means current directory
                continue;
            }
            if (part === '..') {
                //go up one directory
                result.pop();
            } else {
                result.push(part);
            }
        }
        return result.join(path.sep);
    }

    /**
     * Compute the relative path from the source file to the target file
     * @param pkgSrcPath  - the absolute path to the source, where cwd is the package location
     * @param pkgTargetPath  - the absolute path to the target, where cwd is the package location
     */
    public getRelativePath(pkgSrcPath: string, pkgTargetPath: string) {
        pkgSrcPath = path.normalize(pkgSrcPath);
        pkgTargetPath = path.normalize(pkgTargetPath);

        //break by path separator
        let sourceParts = pkgSrcPath.split(path.sep);
        let targetParts = pkgTargetPath.split(path.sep);

        let commonParts = [] as string[];
        //find their common root
        for (let i = 0; i < targetParts.length; i++) {
            if (targetParts[i].toLowerCase() === sourceParts[i].toLowerCase()) {
                commonParts.push(targetParts[i]);
            } else {
                //we found a non-matching part...so no more commonalities past this point
                break;
            }
        }

        //throw out the common parts from both sets
        sourceParts.splice(0, commonParts.length);
        targetParts.splice(0, commonParts.length);

        //throw out the filename part of source
        sourceParts.splice(sourceParts.length - 1, 1);
        //start out by adding updir paths for each remaining source part
        let resultParts = sourceParts.map(() => '..');

        //now add every target part
        resultParts = [...resultParts, ...targetParts];
        return path.join(...resultParts);
    }

    public getImportPackagePath(srcPath: string, pkgTargetPath: string) {
        const srcExt = this.getExtension(srcPath);
        const lowerSrcExt = srcExt.toLowerCase();
        const lowerTargetExt = this.getExtension(pkgTargetPath).toLowerCase();
        if (lowerSrcExt === '.bs' && lowerTargetExt === '.brs') {
            // if source is .bs, use that as the import extenstion
            return pkgTargetPath.substring(0, pkgTargetPath.length - lowerTargetExt.length) + srcExt;
        }
        return pkgTargetPath;
    }

    /**
     * Walks left in a DottedGetExpression and returns a VariableExpression if found, or undefined if not found
     */
    public findBeginningVariableExpression(dottedGet: DottedGetExpression): VariableExpression | undefined {
        let left: any = dottedGet;
        while (left) {
            if (isVariableExpression(left)) {
                return left;
            } else if (isDottedGetExpression(left)) {
                left = left.obj;
            } else {
                break;
            }
        }
    }

    /**
     * Do `a` and `b` overlap by at least one character. This returns false if they are at the edges. Here's some examples:
     * ```
     * | true | true | true | true | true | false | false | false | false |
     * |------|------|------|------|------|-------|-------|-------|-------|
     * | aa   |  aaa |  aaa | aaa  |  a   |  aa   |    aa | a     |     a |
     * |  bbb | bb   |  bbb |  b   | bbb  |    bb |  bb   |     b | a     |
     * ```
     */
    public rangesIntersect(a: Range | undefined, b: Range | undefined) {
        //stop if the either range is misisng
        if (!a || !b) {
            return false;
        }

        // Check if `a` is before `b`
        if (a.end.line < b.start.line || (a.end.line === b.start.line && a.end.character <= b.start.character)) {
            return false;
        }

        // Check if `b` is before `a`
        if (b.end.line < a.start.line || (b.end.line === a.start.line && b.end.character <= a.start.character)) {
            return false;
        }

        // These ranges must intersect
        return true;
    }

    /**
     * Do `a` and `b` overlap by at least one character or touch at the edges
     * ```
     * | true | true | true | true | true | true  | true  | false | false |
     * |------|------|------|------|------|-------|-------|-------|-------|
     * | aa   |  aaa |  aaa | aaa  |  a   |  aa   |    aa | a     |     a |
     * |  bbb | bb   |  bbb |  b   | bbb  |    bb |  bb   |     b | a     |
     * ```
     */
    public rangesIntersectOrTouch(a: Range | undefined, b: Range | undefined) {
        //stop if the either range is misisng
        if (!a || !b) {
            return false;
        }
        // Check if `a` is before `b`
        if (a.end.line < b.start.line || (a.end.line === b.start.line && a.end.character < b.start.character)) {
            return false;
        }

        // Check if `b` is before `a`
        if (b.end.line < a.start.line || (b.end.line === a.start.line && b.end.character < a.start.character)) {
            return false;
        }

        // These ranges must intersect
        return true;
    }

    /**
     * Test if `position` is in `range`. If the position is at the edges, will return true.
     * Adapted from core vscode
     */
    public rangeContains(range: Range | undefined, position: Position | undefined) {
        return this.comparePositionToRange(position, range) === 0;
    }

    public comparePositionToRange(position: Position | undefined, range: Range | undefined) {
        //stop if the either range is missng
        if (!position || !range) {
            return 0;
        }

        if (this.comparePosition(position, range.start) < 0) {
            return -1;
        }
        if (this.comparePosition(position, range.end) > 0) {
            return 1;
        }
        return 0;
    }

    public comparePosition(a: Position | undefined, b: Position) {
        //stop if the either position is missing
        if (!a || !b) {
            return 0;
        }

        if (a.line < b.line || (a.line === b.line && a.character < b.character)) {
            return -1;
        }
        if (a.line > b.line || (a.line === b.line && a.character > b.character)) {
            return 1;
        }
        return 0;
    }

    /**
     * Is the inner range completely enclosed in the outer range
     */
    public isRangeInRange(inner: Range, outer: Range) {
        return this.comparePosition(inner.start, outer.start) === 1 &&
            this.comparePosition(inner.end, outer.end) === -1;
    }

    /**
     * Combine all the documentation for a node - uses the AstNode's leadingTrivia property
     * @param node the node to get the documentation for
     * @param options extra options
     * @param options.prettyPrint if true, will format the comment text for markdown
     * @param options.commentTokens out Array of tokens that match the comment lines
     */
    public getNodeDocumentation(node: AstNode, options: { prettyPrint?: boolean; commentTokens?: Token[] } = { prettyPrint: true }) {
        if (!node) {
            return '';
        }
        options = options ?? { prettyPrint: true };
        options.commentTokens = options.commentTokens ?? [];
        const nodeTrivia = node.leadingTrivia ?? [];
        const leadingTrivia = isStatement(node)
            ? [...(node.annotations?.map(anno => anno.leadingTrivia ?? []).flat() ?? []), ...nodeTrivia]
            : nodeTrivia;
        const tokens = leadingTrivia?.filter(t => t.kind === TokenKind.Newline || t.kind === TokenKind.Comment);
        const comments = [] as Token[];

        let newLinesInRow = 0;
        for (let i = tokens.length - 1; i >= 0; i--) {
            const token = tokens[i];
            //skip whitespace and newline chars
            if (token.kind === TokenKind.Comment) {
                comments.push(token);
                newLinesInRow = 0;
            } else if (token.kind === TokenKind.Newline) {
                //skip these tokens
                newLinesInRow++;

                if (newLinesInRow > 1) {
                    // stop processing on empty line.
                    break;
                }
                //any other token means there are no more comments
            } else {
                break;
            }
        }
        const jsDocCommentBlockLine = /(\/\*{2,}|\*{1,}\/)/i;
        let usesjsDocCommentBlock = false;
        if (comments.length === 0) {
            return '';
        }
        return comments.reverse()
            .map(x => ({ line: x.text.replace(/^('|rem)/i, '').trim(), token: x }))
            .filter(({ line }) => {
                if (jsDocCommentBlockLine.exec(line)) {
                    usesjsDocCommentBlock = true;
                    return false;
                }
                return true;
            }).map(({ line, token }) => {
                if (usesjsDocCommentBlock) {
                    if (line.startsWith('*')) {
                        //remove jsDoc leading '*'
                        line = line.slice(1).trim();
                    }
                }
                if (options.prettyPrint && line.startsWith('@')) {
                    // Handle jsdoc/brightscriptdoc tags specially
                    // make sure they are on their own markdown line, and add italics
                    const firstSpaceIndex = line.indexOf(' ');
                    if (firstSpaceIndex === -1) {
                        return `\n_${line}_`;
                    }
                    const firstWord = line.substring(0, firstSpaceIndex);
                    return `\n_${firstWord}_ ${line.substring(firstSpaceIndex + 1)}`;
                }
                if (options.commentTokens) {
                    options.commentTokens.push(token);
                }
                return line;
            }).join('\n');
    }

    /**
     * Prefixes a component name so it can be used as type in the symbol table, without polluting available symbols
     *
     * @param sgNodeName the Name of the component
     * @returns the node name, prefixed with `roSGNode`
     */
    public getSgNodeTypeName(sgNodeName: string) {
        return 'roSGNode' + sgNodeName;
    }

    /**
     * Force the drive letter to lower case
     */
    public driveLetterToLower(fullPath: string) {
        if (fullPath) {
            let firstCharCode = fullPath.charCodeAt(0);
            if (
                //is upper case A-Z
                firstCharCode >= 65 && firstCharCode <= 90 &&
                //next char is colon
                fullPath[1] === ':'
            ) {
                fullPath = fullPath[0].toLowerCase() + fullPath.substring(1);
            }
        }
        return fullPath;
    }

    /**
     * Replace the first instance of `search` in `subject` with `replacement`
     */
    public replaceCaseInsensitive(subject: string, search: string, replacement: string) {
        let idx = subject.toLowerCase().indexOf(search.toLowerCase());
        if (idx > -1) {
            let result = subject.substring(0, idx) + replacement + subject.substring(idx + search.length);
            return result;
        } else {
            return subject;
        }
    }

    /**
     * Does the string appear to be a uri (i.e. does it start with `file:`)
     */
    public isUriLike(filePath: string) {
        return filePath?.indexOf('file:') === 0;// eslint-disable-line @typescript-eslint/prefer-string-starts-ends-with
    }

    /**
     * Given a file path, convert it to a URI string
     */
    public pathToUri(filePath: string) {
        if (!filePath) {
            return filePath;
        } else if (this.isUriLike(filePath)) {
            return filePath;
        } else {
            return URI.file(filePath).toString();
        }
    }

    /**
     * Given a URI, convert that to a regular fs path
     */
    public uriToPath(uri: string) {
        //if this doesn't look like a URI, then assume it's already a path
        if (this.isUriLike(uri) === false) {
            return uri;
        }
        let parsedPath = URI.parse(uri).fsPath;

        //Uri annoyingly converts all drive letters to lower case...so this will bring back whatever case it came in as
        let match = /\/\/\/([a-z]:)/i.exec(uri);
        if (match) {
            let originalDriveCasing = match[1];
            parsedPath = originalDriveCasing + parsedPath.substring(2);
        }
        const normalizedPath = path.normalize(parsedPath);
        return normalizedPath;
    }

    /**
     * Get paths to all files on disc that match this project's source list
     */
    public async getFilePaths(options: FinalizedBsConfig) {
        let rootDir = this.getRootDir(options);

        let files = await rokuDeploy.getFilePaths(options.files, rootDir);
        return files;
    }

    /**
     * Given a path to a brs file, compute the path to a theoretical d.bs file.
     * Only `.brs` files can have typedef path, so return undefined for everything else
     */
    public getTypedefPath(brsSrcPath: string) {
        const typedefPath = brsSrcPath
            .replace(/\.brs$/i, '.d.bs')
            .toLowerCase();

        if (typedefPath.endsWith('.d.bs')) {
            return typedefPath;
        } else {
            return undefined;
        }
    }

    /**
     * Set a timeout for the specified milliseconds, and resolve the promise once the timeout is finished.
     * @param milliseconds the minimum number of milliseconds to sleep for
     */
    public sleep(milliseconds: number) {
        return new Promise((resolve) => {
            //if milliseconds is 0, don't actually timeout (improves unit test throughput)
            if (milliseconds === 0) {
                process.nextTick(resolve);
            } else {
                setTimeout(resolve, milliseconds);
            }
        });
    }

    /**
     * Determines if the position is greater than the range. This means
     * the position does not touch the range, and has a position greater than the end
     * of the range. A position that touches the last line/char of a range is considered greater
     * than the range, because the `range.end` is EXclusive
     */
    public positionIsGreaterThanRange(position: Position, range: Range) {

        //if the position is a higher line than the range
        if (position.line > range.end.line) {
            return true;
        } else if (position.line < range.end.line) {
            return false;
        }
        //they are on the same line

        //if the position's char is greater than or equal to the range's
        if (position.character >= range.end.character) {
            return true;
        } else {
            return false;
        }
    }

    /**
     * Get a range back from an object that contains (or is) a range
     */
    public extractRange(rangeIsh: RangeLike): Range | undefined {
        if (!rangeIsh) {
            return undefined;
        } else if ('location' in rangeIsh) {
            return rangeIsh.location?.range;
        } else if ('range' in rangeIsh) {
            return rangeIsh.range;
        } else if (Range.is(rangeIsh)) {
            return rangeIsh;
        } else {
            return undefined;
        }
    }

    /**
     * If the two items have lines that touch
     */
    public linesTouch(first: RangeLike, second: RangeLike) {
        const firstRange = this.extractRange(first);
        const secondRange = this.extractRange(second);
        if (firstRange && secondRange && (
            firstRange.start.line === secondRange.start.line ||
            firstRange.start.line === secondRange.end.line ||
            firstRange.end.line === secondRange.start.line ||
            firstRange.end.line === secondRange.end.line
        )) {
            return true;
        } else {
            return false;
        }
    }

    /**
     * Find a script import that the current position touches, or undefined if not found
     */
    public getScriptImportAtPosition(scriptImports: FileReference[], position: Position): FileReference | undefined {
        let scriptImport = scriptImports.find((x) => {
            return x.filePathRange &&
                x.filePathRange.start.line === position.line &&
                //column between start and end
                position.character >= x.filePathRange.start.character &&
                position.character <= x.filePathRange.end.character;
        });
        return scriptImport;
    }

    /**
     * Given the class name text, return a namespace-prefixed name.
     * If the name already has a period in it, or the namespaceName was not provided, return the class name as is.
     * If the name does not have a period, and a namespaceName was provided, return the class name prepended by the namespace name.
     * If no namespace is provided, return the `className` unchanged.
     */
    public getFullyQualifiedClassName(className: string, namespaceName?: string) {
        if (className?.includes('.') === false && namespaceName) {
            return `${namespaceName}.${className}`;
        } else {
            return className;
        }
    }

    public splitIntoLines(string: string) {
        return string.split(/\r?\n/g);
    }

    public getTextForRange(string: string | string[], range: Range): string {
        let lines: string[];
        if (Array.isArray(string)) {
            lines = string;
        } else {
            lines = this.splitIntoLines(string);
        }

        const start = range.start;
        const end = range.end;

        let endCharacter = end.character;
        // If lines are the same we need to subtract out our new starting position to make it work correctly
        if (start.line === end.line) {
            endCharacter -= start.character;
        }

        let rangeLines = [lines[start.line].substring(start.character)];
        for (let i = start.line + 1; i <= end.line; i++) {
            rangeLines.push(lines[i]);
        }
        const lastLine = rangeLines.pop();
        if (lastLine !== undefined) {
            rangeLines.push(lastLine.substring(0, endCharacter));
        }
        return rangeLines.join('\n');
    }

    /**
     * Helper for creating `Location` objects. Prefer using this function because vscode-languageserver's `Location.create()` is significantly slower at scale
     */
    public createLocationFromRange(uri: string, range: Range): Location {
        return {
            uri: util.pathToUri(uri),
            range: range
        };
    }

    /**
     * Helper for creating `Location` objects from a file and range
     */
    public createLocationFromFileRange(file: BscFile, range: Range): Location {
        return this.createLocationFromRange(this.pathToUri(file?.srcPath), range);
    }

    /**
     * Helper for creating `Location` objects by passing each range value in directly. Prefer using this function because vscode-languageserver's `Location.create()` is significantly slower at scale
     */
    public createLocation(startLine: number, startCharacter: number, endLine: number, endCharacter: number, uri?: string): Location {
        return {
            uri: util.pathToUri(uri),
            range: {
                start: {
                    line: startLine,
                    character: startCharacter
                },
                end: {
                    line: endLine,
                    character: endCharacter
                }
            }
        };
    }

    /**
     * Helper for creating `Range` objects. Prefer using this function because vscode-languageserver's `Range.create()` is significantly slower.
     */
    public createRange(startLine: number, startCharacter: number, endLine: number, endCharacter: number): Range {
        return {
            start: {
                line: startLine,
                character: startCharacter
            },
            end: {
                line: endLine,
                character: endCharacter
            }
        };
    }

    /**
     * Create a `Range` from two `Position`s
     */
    public createRangeFromPositions(startPosition: Position, endPosition: Position): Range | undefined {
        startPosition = startPosition ?? endPosition;
        endPosition = endPosition ?? startPosition;
        if (!startPosition && !endPosition) {
            return undefined;
        }
        return this.createRange(startPosition.line, startPosition.character, endPosition.line, endPosition.character);
    }

    /**
     * Clone a range
     */
    public cloneLocation(location: Location) {
        if (location) {
            return {
                uri: location.uri,
                range: {
                    start: {
                        line: location.range.start.line,
                        character: location.range.start.character
                    },
                    end: {
                        line: location.range.end.line,
                        character: location.range.end.character
                    }
                }
            };
        } else {
            return location;
        }
    }

    /**
     * Clone every token
     */
    public cloneToken<T extends Token>(token: T): T {
        if (token) {
            const result = {
                kind: token.kind,
                location: this.cloneLocation(token.location),
                text: token.text,
                isReserved: token.isReserved,
                leadingWhitespace: token.leadingWhitespace,
                leadingTrivia: token.leadingTrivia.map(x => this.cloneToken(x))
            } as Token;
            //handle those tokens that have charCode
            if ('charCode' in token) {
                (result as any).charCode = (token as any).charCode;
            }
            return result as T;
        } else {
            return token;
        }
    }

    /**
     *  Gets the bounding range of a bunch of ranges or objects that have ranges
     *  TODO: this does a full iteration of the args. If the args were guaranteed to be in range order, we could optimize this
     */
    public createBoundingLocation(...locatables: Array<{ location?: Location } | Location | { range?: Range } | Range | undefined>): Location | undefined {
        let uri: string | undefined;
        let startPosition: Position | undefined;
        let endPosition: Position | undefined;

        for (let locatable of locatables) {
            let range: Range;
            if (!locatable) {
                continue;
            } else if ('location' in locatable) {
                range = locatable.location?.range;
                if (!uri) {
                    uri = locatable.location?.uri;
                }
            } else if (Location.is(locatable)) {
                range = locatable.range;
                if (!uri) {
                    uri = locatable.uri;
                }
            } else if ('range' in locatable) {
                range = locatable.range;
            } else {
                range = locatable as Range;
            }

            //skip undefined locations or locations without a range
            if (!range) {
                continue;
            }

            if (!startPosition) {
                startPosition = range.start;
            } else if (this.comparePosition(range.start, startPosition) < 0) {
                startPosition = range.start;
            }
            if (!endPosition) {
                endPosition = range.end;
            } else if (this.comparePosition(range.end, endPosition) > 0) {
                endPosition = range.end;
            }
        }
        if (startPosition && endPosition) {
            return util.createLocation(startPosition.line, startPosition.character, endPosition.line, endPosition.character, uri);
        } else {
            return undefined;
        }
    }

    /**
     *  Gets the bounding range of a bunch of ranges or objects that have ranges
     *  TODO: this does a full iteration of the args. If the args were guaranteed to be in range order, we could optimize this
     */
    public createBoundingRange(...locatables: Array<RangeLike>): Range | undefined {
        return this.createBoundingLocation(...locatables)?.range;
    }

    /**
     * Gets the bounding range of an object that contains a bunch of tokens
     * @param tokens Object with tokens in it
     * @returns Range containing all the tokens
     */
    public createBoundingLocationFromTokens(tokens: Record<string, { location?: Location }>): Location | undefined {
        let uri: string;
        let startPosition: Position | undefined;
        let endPosition: Position | undefined;
        for (let key in tokens) {
            let token = tokens?.[key];
            let locatableRange = token?.location?.range;
            if (!locatableRange) {
                continue;
            }

            if (!startPosition) {
                startPosition = locatableRange.start;
            } else if (this.comparePosition(locatableRange.start, startPosition) < 0) {
                startPosition = locatableRange.start;
            }
            if (!endPosition) {
                endPosition = locatableRange.end;
            } else if (this.comparePosition(locatableRange.end, endPosition) > 0) {
                endPosition = locatableRange.end;
            }
            if (!uri) {
                uri = token.location.uri;
            }
        }
        if (startPosition && endPosition) {
            return this.createLocation(startPosition.line, startPosition.character, endPosition.line, endPosition.character, uri);
        } else {
            return undefined;
        }
    }

    /**
     * Create a `Position` object. Prefer this over `Position.create` for performance reasons.
     */
    public createPosition(line: number, character: number) {
        return {
            line: line,
            character: character
        };
    }

    /**
     * Convert a token into a BscType
     */
    public tokenToBscType(token: Token) {
        // eslint-disable-next-line @typescript-eslint/switch-exhaustiveness-check
        switch (token.kind) {
            case TokenKind.Boolean:
                return BooleanType.instance;
            case TokenKind.True:
            case TokenKind.False:
                return BooleanType.instance;
            case TokenKind.Double:
                return DoubleType.instance;
            case TokenKind.DoubleLiteral:
                return DoubleType.instance;
            case TokenKind.Dynamic:
                return DynamicType.instance;
            case TokenKind.Float:
                return FloatType.instance;
            case TokenKind.FloatLiteral:
                return FloatType.instance;
            case TokenKind.Function:
                return FunctionType.instance;
            case TokenKind.Integer:
                return IntegerType.instance;
            case TokenKind.IntegerLiteral:
                return IntegerType.instance;
            case TokenKind.Invalid:
                return InvalidType.instance;
            case TokenKind.LongInteger:
                return LongIntegerType.instance;
            case TokenKind.LongIntegerLiteral:
                return LongIntegerType.instance;
            case TokenKind.Object:
                return ObjectType.instance;
            case TokenKind.String:
                return StringType.instance;
            case TokenKind.StringLiteral:
            case TokenKind.TemplateStringExpressionBegin:
            case TokenKind.TemplateStringExpressionEnd:
            case TokenKind.TemplateStringQuasi:
                return StringType.instance;
            case TokenKind.Void:
                return VoidType.instance;
            case TokenKind.Identifier:
                switch (token.text.toLowerCase()) {
                    case 'boolean':
                        return BooleanType.instance;
                    case 'double':
                        return DoubleType.instance;
                    case 'dynamic':
                        return DynamicType.instance;
                    case 'float':
                        return FloatType.instance;
                    case 'function':
                        return FunctionType.instance;
                    case 'integer':
                        return IntegerType.instance;
                    case 'invalid':
                        return InvalidType.instance;
                    case 'longinteger':
                        return LongIntegerType.instance;
                    case 'object':
                        return ObjectType.instance;
                    case 'string':
                        return StringType.instance;
                    case 'void':
                        return VoidType.instance;
                }
        }
    }

    /**
     * Deciphers the correct types for fields based on docs
     * https://developer.roku.com/en-ca/docs/references/scenegraph/xml-elements/interface.md
     * @param typeDescriptor the type descriptor from the docs
     * @returns {BscType} the known type, or dynamic
     */
    public getNodeFieldType(typeDescriptor: string, lookupTable?: SymbolTable): BscType {
        let typeDescriptorLower = typeDescriptor.toLowerCase().trim().replace(/\*/g, '');

        if (typeDescriptorLower.startsWith('as ')) {
            typeDescriptorLower = typeDescriptorLower.substring(3).trim();
        }
        const nodeFilter = (new RegExp(/^\[?(.* node)/, 'i')).exec(typeDescriptorLower);
        if (nodeFilter?.[1]) {
            typeDescriptorLower = nodeFilter[1].trim();
        }
        const parensFilter = (new RegExp(/(.*)\(.*\)/, 'gi')).exec(typeDescriptorLower);
        if (parensFilter?.[1]) {
            typeDescriptorLower = parensFilter[1].trim();
        }

        const bscType = this.tokenToBscType(createToken(TokenKind.Identifier, typeDescriptorLower));
        if (bscType) {
            return bscType;
        }

        function getRect2dType() {
            const rect2dType = new AssociativeArrayType();
            rect2dType.addMember('height', {}, FloatType.instance, SymbolTypeFlag.runtime);
            rect2dType.addMember('width', {}, FloatType.instance, SymbolTypeFlag.runtime);
            rect2dType.addMember('x', {}, FloatType.instance, SymbolTypeFlag.runtime);
            rect2dType.addMember('y', {}, FloatType.instance, SymbolTypeFlag.runtime);
            return rect2dType;
        }

        function getColorType() {
            return unionTypeFactory([IntegerType.instance, StringType.instance]);
        }

        //check for uniontypes
        const multipleTypes = typeDescriptorLower.split(' or ').map(s => s.trim());
        if (multipleTypes.length > 1) {
            const individualTypes = multipleTypes.map(t => this.getNodeFieldType(t, lookupTable));
            return unionTypeFactory(individualTypes);
        }

        const typeIsArray = typeDescriptorLower.startsWith('array of ') || typeDescriptorLower.startsWith('roarray of ');

        if (typeIsArray) {
            const ofSearch = ' of ';
            const arrayPrefixLength = typeDescriptorLower.indexOf(ofSearch) + ofSearch.length;
            let arrayOfTypeName = typeDescriptorLower.substring(arrayPrefixLength); //cut off beginnin, eg. 'array of' or 'roarray of'
            if (arrayOfTypeName.endsWith('s')) {
                // remove "s" in "floats", etc.
                arrayOfTypeName = arrayOfTypeName.substring(0, arrayOfTypeName.length - 1);
            }
            if (arrayOfTypeName.endsWith('\'')) {
                // remove "'" in "float's", etc.
                arrayOfTypeName = arrayOfTypeName.substring(0, arrayOfTypeName.length - 1);
            }
            if (arrayOfTypeName === 'rectangle') {
                arrayOfTypeName = 'rect2d';
            }
            let arrayType = this.getNodeFieldType(arrayOfTypeName, lookupTable);
            return new ArrayType(arrayType);
        } else if (typeDescriptorLower.startsWith('option ')) {
            const actualTypeName = typeDescriptorLower.substring('option '.length); //cut off beginning 'option '
            return this.getNodeFieldType(actualTypeName, lookupTable);
        } else if (typeDescriptorLower.startsWith('value ')) {
            const actualTypeName = typeDescriptorLower.substring('value '.length); //cut off beginning 'value '
            return this.getNodeFieldType(actualTypeName, lookupTable);
        } else if (typeDescriptorLower === 'n/a') {
            return DynamicType.instance;
        } else if (typeDescriptorLower === 'uri') {
            return StringType.instance;
        } else if (typeDescriptorLower === 'color') {
            return getColorType();
        } else if (typeDescriptorLower === 'vector2d' || typeDescriptorLower === 'floatarray') {
            return new ArrayType(FloatType.instance);
        } else if (typeDescriptorLower === 'vector2darray') {
            return new ArrayType(new ArrayType(FloatType.instance));
        } else if (typeDescriptorLower === 'intarray') {
            return new ArrayType(IntegerType.instance);
        } else if (typeDescriptorLower === 'colorarray') {
            return new ArrayType(getColorType());
        } else if (typeDescriptorLower === 'boolarray') {
            return new ArrayType(BooleanType.instance);
        } else if (typeDescriptorLower === 'stringarray' || typeDescriptorLower === 'strarray') {
            return new ArrayType(StringType.instance);
        } else if (typeDescriptorLower === 'int') {
            return IntegerType.instance;
        } else if (typeDescriptorLower === 'time') {
            return DoubleType.instance;
        } else if (typeDescriptorLower === 'str') {
            return StringType.instance;
        } else if (typeDescriptorLower === 'bool') {
            return BooleanType.instance;
        } else if (typeDescriptorLower === 'array' || typeDescriptorLower === 'roarray') {
            return new ArrayType();
        } else if (typeDescriptorLower === 'assocarray' ||
            typeDescriptorLower === 'associative array' ||
            typeDescriptorLower === 'associativearray' ||
            typeDescriptorLower === 'roassociativearray' ||
            typeDescriptorLower.startsWith('associative array of') ||
            typeDescriptorLower.startsWith('associativearray of') ||
            typeDescriptorLower.startsWith('roassociativearray of')
        ) {
            return new AssociativeArrayType();
        } else if (typeDescriptorLower === 'node') {
            return ComponentType.instance;
        } else if (typeDescriptorLower === 'nodearray') {
            return new ArrayType(ComponentType.instance);
        } else if (typeDescriptorLower === 'rect2d') {
            return getRect2dType();
        } else if (typeDescriptorLower === 'rect2darray') {
            return new ArrayType(getRect2dType());
        } else if (typeDescriptorLower === 'font') {
            return this.getNodeFieldType('roSGNodeFont', lookupTable);
        } else if (typeDescriptorLower === 'contentnode') {
            return this.getNodeFieldType('roSGNodeContentNode', lookupTable);
        } else if (typeDescriptorLower.endsWith(' node')) {
            return this.getNodeFieldType('roSgNode' + typeDescriptorLower.substring(0, typeDescriptorLower.length - 5), lookupTable);
        } else if (lookupTable) {
            //try doing a lookup
            return lookupTable.getSymbolType(typeDescriptorLower, {
                flags: SymbolTypeFlag.typetime,
                fullName: typeDescriptor,
                tableProvider: () => lookupTable
            });
        }

        return DynamicType.instance;
    }

    /**
     * Return the type of the result of a binary operator
     * Note: compound assignments (eg. +=) internally use a binary expression, so that's why TokenKind.PlusEqual, etc. are here too
     */
    public binaryOperatorResultType(leftType: BscType, operator: Token, rightType: BscType): BscType {
        if ((isAnyReferenceType(leftType) && !leftType.isResolvable()) ||
            (isAnyReferenceType(rightType) && !rightType.isResolvable())) {
            return new BinaryOperatorReferenceType(leftType, operator, rightType, (lhs, op, rhs) => {
                return this.binaryOperatorResultType(lhs, op, rhs);
            });
        }

        // Try to find a common value of union type
        leftType = getUniqueType([leftType], unionTypeFactory);
        rightType = getUniqueType([rightType], unionTypeFactory);

        if (isUnionType(leftType)) {
            leftType = this.getHighestPriorityType(leftType.types);
        }
        if (isUnionType(rightType)) {
            rightType = this.getHighestPriorityType(rightType.types);
        }

        if (isVoidType(leftType) || isVoidType(rightType) || isUninitializedType(leftType) || isUninitializedType(rightType)) {
            return undefined;
        }

        if (isEnumMemberType(leftType)) {
            leftType = leftType.underlyingType;
        }
        if (isEnumMemberType(rightType)) {
            rightType = rightType.underlyingType;
        }

        // treat object type like dynamic
        if (isObjectType(leftType)) {
            leftType = DynamicType.instance;
        }
        if (isObjectType(rightType)) {
            rightType = DynamicType.instance;
        }

        let hasDouble = isDoubleTypeLike(leftType) || isDoubleTypeLike(rightType);
        let hasFloat = isFloatTypeLike(leftType) || isFloatTypeLike(rightType);
        let hasLongInteger = isLongIntegerTypeLike(leftType) || isLongIntegerTypeLike(rightType);
        let hasInvalid = isInvalidTypeLike(leftType) || isInvalidTypeLike(rightType);
        let hasDynamic = isDynamicType(leftType) || isDynamicType(rightType);
        let bothDynamic = isDynamicType(leftType) && isDynamicType(rightType);
        let bothNumbers = isNumberTypeLike(leftType) && isNumberTypeLike(rightType);
        let hasNumber = isNumberTypeLike(leftType) || isNumberTypeLike(rightType);
        let bothStrings = isStringTypeLike(leftType) && isStringTypeLike(rightType);
        let hasString = isStringTypeLike(leftType) || isStringTypeLike(rightType);
        let hasBoolean = isBooleanTypeLike(leftType) || isBooleanTypeLike(rightType);
        let eitherBooleanOrNum = (isNumberTypeLike(leftType) || isBooleanTypeLike(leftType)) && (isNumberTypeLike(rightType) || isBooleanTypeLike(rightType));

        let leftIsPrimitive = isPrimitiveType(leftType);
        let rightIsPrimitive = isPrimitiveType(rightType);
        let hasPrimitive = leftIsPrimitive || rightIsPrimitive;

        let nonDynamicType: BscType;
        if (hasPrimitive) {
            nonDynamicType = leftIsPrimitive ? leftType : rightType;
        }

        // eslint-disable-next-line @typescript-eslint/switch-exhaustiveness-check
        switch (operator.kind) {
            // Math operators
            case TokenKind.Plus:
            case TokenKind.PlusEqual:
                if (bothStrings) {
                    // "string" + "string" is the only binary expression allowed with strings
                    return StringType.instance;
                } else if (hasString && hasDynamic) {
                    // assume dynamicValue is a string
                    return StringType.instance;
                }
            // eslint-disable-next-line no-fallthrough
            case TokenKind.Minus:
            case TokenKind.MinusEqual:
            case TokenKind.Star:
            case TokenKind.StarEqual:
            case TokenKind.Mod:
                if (bothNumbers) {
                    if (hasDouble) {
                        return DoubleType.instance;
                    } else if (hasFloat) {
                        return FloatType.instance;

                    } else if (hasLongInteger) {
                        return LongIntegerType.instance;
                    }
                    return IntegerType.instance;
                } else if (hasNumber && hasDynamic) {
                    // assume dynamic is a number
                    return nonDynamicType;
                }
                break;
            case TokenKind.Forwardslash:
            case TokenKind.ForwardslashEqual:
                if (bothNumbers) {
                    if (hasDouble) {
                        return DoubleType.instance;
                    } else if (hasFloat) {
                        return FloatType.instance;

                    } else if (hasLongInteger) {
                        return LongIntegerType.instance;
                    }
                    return FloatType.instance;
                } else if (hasNumber && hasDynamic) {
                    // assume dynamic is a number
                    return nonDynamicType;
                }
                break;
            case TokenKind.Backslash:
            case TokenKind.BackslashEqual:
                if (bothNumbers) {
                    if (hasLongInteger) {
                        return LongIntegerType.instance;
                    }
                    return IntegerType.instance;
                } else if (hasNumber && hasDynamic) {
                    // assume dynamic is a number
                    return IntegerType.instance;
                }
                break;
            case TokenKind.Caret:
                if (bothNumbers) {
                    if (hasDouble || hasLongInteger) {
                        return DoubleType.instance;
                    } else if (hasFloat) {
                        return FloatType.instance;
                    }
                    return IntegerType.instance;
                } else if (hasNumber && hasDynamic) {
                    // assume dynamic is a number
                    return IntegerType.instance;
                }
                break;
            // Bitshift operators
            case TokenKind.LeftShift:
            case TokenKind.LeftShiftEqual:
            case TokenKind.RightShift:
            case TokenKind.RightShiftEqual:
                if (bothNumbers) {
                    if (hasLongInteger) {
                        return LongIntegerType.instance;
                    }
                    // Bitshifts are allowed with non-integer numerics
                    // but will always truncate to ints
                    return IntegerType.instance;
                } else if (hasNumber && hasDynamic) {
                    // assume dynamic is a number
                    return IntegerType.instance;
                }
                break;
            // Comparison operators
            // All comparison operators result in boolean
            case TokenKind.Equal:
            case TokenKind.LessGreater:
                // = and <> can accept invalid / dynamic
                if (hasDynamic || hasInvalid || bothStrings || eitherBooleanOrNum) {
                    return BooleanType.instance;
                }
                break;
            case TokenKind.Greater:
            case TokenKind.Less:
            case TokenKind.GreaterEqual:
            case TokenKind.LessEqual:
                if (bothStrings || bothNumbers) {
                    return BooleanType.instance;
                } else if ((hasNumber || hasString) && hasDynamic) {
                    // assume dynamic is a valid type
                    return BooleanType.instance;
                }
                break;
            // Logical or bitwise operators
            case TokenKind.Or:
            case TokenKind.And:
                if (bothNumbers) {
                    // "and"/"or" represent bitwise operators
                    if (hasLongInteger && !hasDouble && !hasFloat) {
                        // 2 long ints or long int and int
                        return LongIntegerType.instance;
                    }
                    return IntegerType.instance;
                } else if (eitherBooleanOrNum) {
                    // "and"/"or" represent logical operators
                    return BooleanType.instance;
                } else if (hasNumber && hasDynamic) {
                    // assume dynamic is a valid type
                    return IntegerType.instance;
                } else if (hasBoolean && hasDynamic) {
                    // assume dynamic is a valid type
                    return BooleanType.instance;
                }
                break;
        }
        if (bothDynamic) {
            return DynamicType.instance;
        }
        return undefined;
    }

    public getHighestPriorityType(types: BscType[], depth = 0): BscType {
        let result: BscType;
        if (depth > 4) {
            // shortcut for very complicated types, or self-referencing union types
            return DynamicType.instance;
        }
        for (let type of types) {
            if (isUnionType(type)) {
                type = getUniqueType([type], unionTypeFactory);
                if (isUnionType(type)) {
                    type = this.getHighestPriorityType(type.types, depth + 1);
                }
            }
            if (!result) {
                result = type;
            } else {
                if (type.binaryOpPriorityLevel < result.binaryOpPriorityLevel) {
                    result = type;
                } else if (type.binaryOpPriorityLevel === result.binaryOpPriorityLevel && !result.isEqual(type)) {
                    // equal priority types, but not equal types, like Boolean and String... just be dynamic at this point
                    result = DynamicType.instance;
                }
            }
            if (isUninitializedType(type)) {
                return type;
            }
            if (isVoidType(type)) {
                return type;
            }
            if (isInvalidTypeLike(type)) {
                return type;
            }
            if (isObjectType(type) && !isDynamicType(type)) {
                result = type;
            }
            if (isDynamicType(type)) {
                result = type;
            }
        }
        return result ?? DynamicType.instance;
    }

    /**
     * Return the type of the result of a unary operator
     */
    public unaryOperatorResultType(operator: Token, exprType: BscType): BscType {

        if (isUnionType(exprType)) {
            exprType = this.getHighestPriorityType(exprType.types);
        }

        if (isVoidType(exprType) || isInvalidTypeLike(exprType) || isUninitializedType(exprType)) {
            return undefined;
        }


        if (isDynamicType(exprType) || isObjectType(exprType)) {
            return exprType;
        }

        // eslint-disable-next-line @typescript-eslint/switch-exhaustiveness-check
        switch (operator.kind) {
            // Math operators
            case TokenKind.Plus: // (`num = +num` is valid syntax)
            case TokenKind.Minus:
                if (isNumberTypeLike(exprType)) {
                    // a negative number will be the same type, eg, double->double, int->int, etc.
                    return this.getUnboxedType(exprType);
                }
                break;
            case TokenKind.Not:
                if (isBooleanTypeLike(exprType)) {
                    return BooleanType.instance;
                } else if (isNumberTypeLike(exprType)) {
                    //numbers can be "notted"
                    // by default they go to ints, except longints, which stay that way
                    if (isLongIntegerTypeLike(exprType)) {
                        return LongIntegerType.instance;
                    }
                    return IntegerType.instance;
                }
                break;
        }
        return undefined;
    }

    public getUnboxedType(boxedType: BscType): BscType {
        if (isIntegerTypeLike(boxedType)) {
            return IntegerType.instance;
        } else if (isLongIntegerTypeLike(boxedType)) {
            return LongIntegerType.instance;
        } else if (isFloatTypeLike(boxedType)) {
            return FloatType.instance;
        } else if (isDoubleTypeLike(boxedType)) {
            return DoubleType.instance;
        } else if (isBooleanTypeLike(boxedType)) {
            return BooleanType.instance;
        } else if (isStringTypeLike(boxedType)) {
            return StringType.instance;
        } else if (isInvalidTypeLike(boxedType)) {
            return InvalidType.instance;
        }
        return boxedType;
    }

    /**
     * Get the extension for the given file path. Basically the part after the final dot, except for
     * `d.bs` which is treated as single extension
     * @returns the file extension (i.e. ".d.bs", ".bs", ".brs", ".xml", ".jpg", etc...)
     */
    public getExtension(filePath: string) {
        filePath = filePath.toLowerCase();
        if (filePath.endsWith('.d.bs')) {
            return '.d.bs';
        } else {
            return path.extname(filePath).toLowerCase();
        }
    }

    /**
     * Load and return the list of plugins
     */
    public loadPlugins(cwd: string, pathOrModules: string[], onError?: (pathOrModule: string, err: Error) => void): Plugin[] {
        const logger = createLogger();
        return pathOrModules.reduce<Plugin[]>((acc, pathOrModule) => {
            if (typeof pathOrModule === 'string') {
                try {
                    const loaded = requireRelative(pathOrModule, cwd);
                    const theExport: Plugin | PluginFactory = loaded.default ? loaded.default : loaded;

                    let plugin: Plugin | undefined;

                    // legacy plugins returned a plugin object. If we find that, then add a warning
                    if (typeof theExport === 'object') {
                        logger.warn(`Plugin "${pathOrModule}" was loaded as a singleton. Please contact the plugin author to update to the factory pattern.\n`);
                        plugin = theExport;

                        // the official plugin format is a factory function that returns a new instance of a plugin.
                    } else if (typeof theExport === 'function') {
                        plugin = theExport({
                            version: this.getBrighterScriptVersion()
                        });
                    } else {
                        //this should never happen; somehow an invalid plugin has made it into here
                        throw new Error(`TILT: Encountered an invalid plugin: ${String(plugin)}`);
                    }

                    if (!plugin.name) {
                        plugin.name = pathOrModule;
                    }
                    acc.push(plugin);
                } catch (err: any) {
                    if (onError) {
                        onError(pathOrModule, err);
                    } else {
                        throw err;
                    }
                }
            }
            return acc;
        }, []);
    }

    /**
     * Gathers expressions, variables, and unique names from an expression.
     * This is mostly used for the ternary expression
     */
    public getExpressionInfo(expression: Expression, file: BrsFile): ExpressionInfo {
        const expressions = [expression];
        const variableExpressions = [] as VariableExpression[];
        const uniqueVarNames = new Set<string>();

        function expressionWalker(expression) {
            if (isExpression(expression)) {
                expressions.push(expression);
            }
            if (isVariableExpression(expression)) {
                variableExpressions.push(expression);
                uniqueVarNames.add(expression.tokens.name.text);
            }
        }

        // Collect all expressions. Most of these expressions are fairly small so this should be quick!
        // This should only be called during transpile time and only when we actually need it.
        expression?.walk(expressionWalker, {
            walkMode: WalkMode.visitExpressions
        });

        //handle the expression itself (for situations when expression is a VariableExpression)
        expressionWalker(expression);

        const scope = file.program.getFirstScopeForFile(file);
        let filteredVarNames = [...uniqueVarNames];
        if (scope) {
            filteredVarNames = filteredVarNames.filter((varName: string) => {
                const varNameLower = varName.toLowerCase();
                // TODO: include namespaces in this filter
                return !scope.getEnumMap().has(varNameLower) &&
                    !scope.getConstMap().has(varNameLower);
            });
        }

        return { expressions: expressions, varExpressions: variableExpressions, uniqueVarNames: filteredVarNames };
    }


    public concatAnnotationLeadingTrivia(stmt: Statement): Token[] {
        return [...(stmt.annotations?.map(anno => anno.leadingTrivia ?? []).flat() ?? []), ...stmt.leadingTrivia];
    }

    /**
     * Create a SourceNode that maps every line to itself. Useful for creating maps for files
     * that haven't changed at all, but we still need the map
     */
    public simpleMap(source: string, src: string) {
        //create a source map from the original source code
        let chunks = [] as (SourceNode | string)[];
        let lines = src.split(/\r?\n/g);
        for (let lineIndex = 0; lineIndex < lines.length; lineIndex++) {
            let line = lines[lineIndex];
            chunks.push(
                lineIndex > 0 ? '\n' : '',
                new SourceNode(lineIndex + 1, 0, source, line)
            );
        }
        return new SourceNode(null, null, source, chunks);
    }

    private isWindows = process.platform === 'win32';
    private standardizePathCache = new Map<string, string>();

    /**
     * Converts a path into a standardized format (drive letter to lower, remove extra slashes, use single slash type, resolve relative parts, etc...)
     */
    public standardizePath(thePath: string): string {
        //if we have the value in cache already, return it
        if (this.standardizePathCache.has(thePath)) {
            return this.standardizePathCache.get(thePath);
        }
        const originalPath = thePath;

        if (typeof thePath !== 'string') {
            return thePath;
        }

        //windows path.normalize will convert all slashes to backslashes and remove duplicates
        if (this.isWindows) {
            thePath = path.win32.normalize(thePath);
        } else {
            //replace all windows or consecutive slashes with path.sep
            thePath = thePath.replace(/[\/\\]+/g, '/');

            // only use path.normalize if dots are present since it's expensive
            if (thePath.includes('./')) {
                thePath = path.posix.normalize(thePath);
            }
        }

        // Lowercase drive letter on Windows-like paths (e.g., "C:/...")
        if (thePath.charCodeAt(1) === 58 /* : */) {
            // eslint-disable-next-line no-var
            var firstChar = thePath.charCodeAt(0);
            if (firstChar >= 65 && firstChar <= 90) {
                thePath = String.fromCharCode(firstChar + 32) + thePath.slice(1);
            }
        }
        this.standardizePathCache.set(originalPath, thePath);
        return thePath;
    }

    /**
     * Given a Diagnostic or BsDiagnostic, return a deep clone of the diagnostic.
     * @param diagnostic the diagnostic to clone
     * @param relatedInformationFallbackLocation a default location to use for all `relatedInformation` entries that are missing a location
     */
    public toDiagnostic(diagnostic: Diagnostic | BsDiagnostic, relatedInformationFallbackLocation: string): Diagnostic {
        let relatedInformation = diagnostic.relatedInformation ?? [];
        if (relatedInformation.length > MAX_RELATED_INFOS_COUNT) {
            const relatedInfoLength = relatedInformation.length;
            relatedInformation = relatedInformation.slice(0, MAX_RELATED_INFOS_COUNT);
            relatedInformation.push({
                message: `...and ${relatedInfoLength - MAX_RELATED_INFOS_COUNT} more`,
                location: util.createLocationFromRange('   ', util.createRange(0, 0, 0, 0))
            });
        }

        const range = (diagnostic as BsDiagnostic).location?.range ??
            (diagnostic as Diagnostic).range;

        let result = {
            severity: diagnostic.severity,
            range: range,
            message: diagnostic.message,
            relatedInformation: relatedInformation.map(x => {

                //clone related information just in case a plugin added circular ref info here
                const clone = { ...x };
                if (!clone.location) {
                    // use the fallback location if available
                    if (relatedInformationFallbackLocation) {
                        clone.location = util.createLocationFromRange(relatedInformationFallbackLocation, range);
                    } else {
                        //remove this related information so it doesn't bring crash the language server
                        return undefined;
                    }
                }
                return clone;
                //filter out null relatedInformation items
            }).filter((x): x is DiagnosticRelatedInformation => Boolean(x)),
            code: diagnostic.code ? diagnostic.code : (diagnostic as BsDiagnostic).legacyCode,
            source: diagnostic.source ?? 'brs'
        } as Diagnostic;
        if (diagnostic?.tags?.length > 0) {
            result.tags = diagnostic.tags;
        }
        return result;
    }

    /**
     * Sort an array of objects that have a Range
     */
    public sortByRange<T extends { range: Range | undefined }>(locatables: T[]) {
        //sort the tokens by range
        return locatables?.sort((a, b) => {
            //handle undefined tokens to prevent crashes
            if (!a?.range) {
                return 1;
            }
            if (!b?.range) {
                return -1;
            }

            //start line
            if (a.range.start.line < b.range.start.line) {
                return -1;
            }
            if (a.range.start.line > b.range.start.line) {
                return 1;
            }
            //start char
            if (a.range.start.character < b.range.start.character) {
                return -1;
            }
            if (a.range.start.character > b.range.start.character) {
                return 1;
            }
            //end line
            if (a.range.end.line < b.range.end.line) {
                return -1;
            }
            if (a.range.end.line > b.range.end.line) {
                return 1;
            }
            //end char
            if (a.range.end.character < b.range.end.character) {
                return -1;
            } else if (a.range.end.character > b.range.end.character) {
                return 1;
            }
            return 0;
        });
    }

    /**
     * Wrap the given code in a markdown code fence (with the language)
     */
    public mdFence(code: string, language = '') {
        return '```' + language + '\n' + code + '\n```';
    }

    /**
     * Gets each part of the dotted get.
     * @param node any ast expression
     * @returns an array of the parts of the dotted get. If not fully a dotted get, then returns undefined
     */
    public getAllDottedGetParts(node: AstNode): Identifier[] | undefined {
        //this is a hot function and has been optimized. Don't rewrite unless necessary
        const parts: Identifier[] = [];
        let nextPart = node;
        loop: while (nextPart) {
            switch (nextPart?.kind) {
                case AstNodeKind.AssignmentStatement:
                    return [(node as AssignmentStatement).tokens.name];
                case AstNodeKind.DottedGetExpression:
                    parts.push((nextPart as DottedGetExpression)?.tokens.name);
                    nextPart = (nextPart as DottedGetExpression).obj;
                    continue;
                case AstNodeKind.CallExpression:
                    nextPart = (nextPart as CallExpression).callee;
                    continue;
                case AstNodeKind.CallfuncExpression:
                    parts.push((nextPart as CallfuncExpression)?.tokens.methodName);
                    nextPart = (nextPart as CallfuncExpression).callee;
                    continue;
                case AstNodeKind.TypeExpression:
                    nextPart = (nextPart as TypeExpression).expression;
                    continue;
                case AstNodeKind.VariableExpression:
                    parts.push((nextPart as VariableExpression)?.tokens.name);
                    break loop;
                case AstNodeKind.LiteralExpression:
                    parts.push((nextPart as LiteralExpression)?.tokens.value as Identifier);
                    break loop;
                case AstNodeKind.IndexedGetExpression:
                    nextPart = (nextPart as unknown as IndexedGetExpression).obj;
                    continue;
                case AstNodeKind.FunctionParameterExpression:
                    return [(nextPart as FunctionParameterExpression).tokens.name];
                case AstNodeKind.GroupingExpression:
                    parts.push(createIdentifier('()', nextPart.location));
                    break loop;
                default:
                    //we found a non-DottedGet expression, so return because this whole operation is invalid.
                    return undefined;
            }
        }
        return parts.reverse();
    }

    /**
     * Given an expression, return all the DottedGet name parts as a string.
     * Mostly used to convert namespaced item full names to a strings
     */
    public getAllDottedGetPartsAsString(node: Expression | Statement, parseMode = ParseMode.BrighterScript, lastSep = '.'): string {
        //this is a hot function and has been optimized. Don't rewrite unless necessary
        /* eslint-disable no-var */
        var sep = parseMode === ParseMode.BrighterScript ? '.' : '_';

        const parts = this.getAllDottedGetParts(node) ?? [];
        var result = parts[0]?.text;
        for (var i = 1; i < parts.length; i++) {
            result += (i === parts.length - 1 && parseMode === ParseMode.BrighterScript ? lastSep : sep) + parts[i].text;
        }
        return result;
        /* eslint-enable no-var */
    }

    /**
     * Break an expression into each part.
     */
    public splitExpression(expression: Expression) {
        const parts: Expression[] = [expression];
        let nextPart = expression;
        while (nextPart) {
            if (isDottedGetExpression(nextPart) || isIndexedGetExpression(nextPart) || isXmlAttributeGetExpression(nextPart)) {
                nextPart = nextPart.obj;

            } else if (isCallExpression(nextPart) || isCallfuncExpression(nextPart)) {
                nextPart = nextPart.callee;

            } else if (isTypeExpression(nextPart)) {
                nextPart = nextPart.expression;
            } else {
                break;
            }
            parts.unshift(nextPart);
        }
        return parts;
    }

    /**
     * Returns an integer if valid, or undefined. Eliminates checking for NaN
     */
    public parseInt(value: any) {
        const result = parseInt(value);
        if (!isNaN(result)) {
            return result;
        } else {
            return undefined;
        }
    }

    /**
     * Converts a range to a string in the format 1:2-3:4
     */
    public rangeToString(range: Range) {
        return `${range?.start?.line}:${range?.start?.character}-${range?.end?.line}:${range?.end?.character}`;
    }

    public validateTooDeepFile(file: (BrsFile | XmlFile)) {
        //find any files nested too deep
        let destPath = file?.destPath?.toString();
        let rootFolder = destPath?.replace(/^pkg:/, '').split(/[\\\/]/)[0].toLowerCase();

        if (isBrsFile(file) && rootFolder !== 'source') {
            return;
        }

        if (isXmlFile(file) && rootFolder !== 'components') {
            return;
        }

        let fileDepth = this.getParentDirectoryCount(destPath);
        if (fileDepth >= 8) {
            file.program?.diagnostics.register({
                ...DiagnosticMessages.detectedTooDeepFileSource(fileDepth),
                location: util.createLocationFromFileRange(file, this.createRange(0, 0, 0, Number.MAX_VALUE))
            });
        }
    }

    /**
     * Execute dispose for a series of disposable items
     * @param disposables a list of functions or disposables
     */
    public applyDispose(disposables: DisposableLike[]) {
        for (const disposable of disposables ?? []) {
            if (typeof disposable === 'function') {
                disposable();
            } else {
                disposable?.dispose?.();
            }
        }
    }

    /**
     * Race a series of promises, and return the first one that resolves AND matches the matcher function.
     * If all of the promises reject, then this will emit an AggregatreError with all of the errors.
     * If at least one promise resolves, then this will log all of the errors to the console
     * If at least one promise resolves but none of them match the matcher, then this will return undefined.
     * @param promises all of the promises to race
     * @param matcher a function that should return true if this value should be kept. Returning any value other than true means `false`
     * @returns the first resolved value that matches the matcher, or undefined if none of them match
     */
    public async promiseRaceMatch<T>(promises: MaybePromise<T>[], matcher: (value: T) => boolean) {
        const workingPromises = [
            ...promises
        ];

        const results: Array<{ value: T; index: number } | { error: Error; index: number }> = [];
        let returnValue: T;

        while (workingPromises.length > 0) {
            //race the promises. If any of them resolve, evaluate it against the matcher. If that passes, return the value. otherwise, eliminate this promise and try again
            const result = await Promise.race(
                workingPromises.map((promise, i) => {
                    return Promise.resolve(promise)
                        .then(value => ({ value: value, index: i }))
                        .catch(error => ({ error: error, index: i }));
                })
            );
            results.push(result);
            //if we got a value and it matches the matcher, return it
            if ('value' in result && matcher?.(result.value) === true) {
                returnValue = result.value;
                break;
            }

            //remove this non-matched (or errored) promise from the list and try again
            workingPromises.splice(result.index, 1);
        }

        const errors = (results as Array<{ error: Error }>)
            .filter(x => 'error' in x)
            .map(x => x.error);

        //if all of them crashed, then reject
        if (promises.length > 0 && errors.length === promises.length) {
            throw new AggregateError(errors, 'All requests failed. First error message: ' + errors[0].message);
        } else {
            //log all of the errors
            for (const error of errors) {
                console.error(error);
            }
        }

        //return the matched value, or undefined if there wasn't one
        return returnValue;
    }

    /**
     * Wraps SourceNode's constructor to be compatible with the TranspileResult type
     */
    public sourceNodeFromTranspileResult(
        line: number | null,
        column: number | null,
        source: string | null,
        chunks?: string | SourceNode | TranspileResult,
        name?: string
    ): SourceNode {
        // we can use a typecast rather than actually transforming the data because SourceNode
        // accepts a more permissive type than its typedef states
        return new SourceNode(line, column, source, chunks as any, name);
    }

    /**
     * Find the index of the last item in the array that matches.
     */
    public findLastIndex<T>(array: T[], matcher: (T) => boolean) {
        for (let i = array.length - 1; i >= 0; i--) {
            if (matcher(array[i])) {
                return i;
            }
        }
    }

    public processTypeChain(typeChain: TypeChainEntry[]): TypeChainProcessResult {
        let fullChainName = '';
        let fullErrorName = '';
        let itemName = '';
        let previousTypeName = '';
        let parentTypeName = '';
        let itemTypeKind = '';
        let parentTypeKind = '';
        let astNode: AstNode;
        let errorLocation: Location;
        let containsDynamic = false;
        let continueResolvingAllItems = true;
        let crossedCallFunc = false;
        for (let i = 0; i < typeChain.length; i++) {
            const chainItem = typeChain[i];
            const dotSep = chainItem.separatorToken?.text ?? '.';
            if (i > 0) {
                fullChainName += dotSep;
            }
            fullChainName += chainItem.name;
            if (continueResolvingAllItems) {
                parentTypeName = previousTypeName;
                parentTypeKind = itemTypeKind;
                fullErrorName = previousTypeName ? `${previousTypeName}${dotSep}${chainItem.name}` : chainItem.name;
                itemTypeKind = (chainItem.type as any)?.kind;

                let typeString = chainItem.type?.toString();
                let typeToFindStringFor = chainItem.type;
                while (typeToFindStringFor) {
                    if (isUnionType(chainItem.type)) {
                        typeString = `(${typeToFindStringFor.toString()})`;
                        break;
                    } else if (isCallableType(typeToFindStringFor)) {
                        if (isTypedFunctionType(typeToFindStringFor) && i < typeChain.length - 1) {
                            typeToFindStringFor = typeToFindStringFor.returnType;
                        } else {
                            typeString = 'function';
                            break;
                        }
                        parentTypeName = previousTypeName;
                    } else if (isNamespaceType(typeToFindStringFor) && parentTypeName) {
                        const chainItemTypeName = typeToFindStringFor.toString();
                        typeString = parentTypeName + '.' + chainItemTypeName;
                        if (chainItemTypeName.toLowerCase().startsWith(parentTypeName.toLowerCase())) {
                            // the following namespace already knows...
                            typeString = chainItemTypeName;
                        }
                        break;
                    } else {
                        typeString = typeToFindStringFor?.toString();
                        break;
                    }
                }

                previousTypeName = typeString ?? '';
                itemName = chainItem.name;
                astNode = chainItem.astNode;
                containsDynamic = containsDynamic || (isDynamicType(chainItem.type) && !isAnyReferenceType(chainItem.type));
                crossedCallFunc = crossedCallFunc || chainItem.data?.isFromCallFunc;
                if (!chainItem.isResolved) {
                    errorLocation = chainItem.location;
                    continueResolvingAllItems = false;
                }
            }
        }
        return {
            itemName: itemName,
            itemTypeKind: itemTypeKind,
            itemParentTypeName: parentTypeName,
            itemParentTypeKind: parentTypeKind,
            fullNameOfItem: fullErrorName,
            fullChainName: fullChainName,
            location: errorLocation,
            containsDynamic: containsDynamic,
            astNode: astNode,
            crossedCallFunc: crossedCallFunc
        };
    }

    public getCircularReferenceDiagnosticDetail(circularReferenceInfo: TypeCircularReferenceInfo, defaultName = ''): string[] {
        if (!circularReferenceInfo || !circularReferenceInfo.referenceChainNames) {
            if (defaultName) {
                return [defaultName];
            }
            return [];
        }

        if (circularReferenceInfo.referenceChainNames[0] === circularReferenceInfo.referenceChainNames[circularReferenceInfo.referenceChainNames.length - 1]) {
            // last element is same as first it will read okay
            return circularReferenceInfo.referenceChainNames;
        }
        return [...circularReferenceInfo.referenceChainNames, circularReferenceInfo.referenceChainNames[0]];
    }


    public isInTypeExpression(expression: AstNode): boolean {
        //TODO: this is much faster than node.findAncestor(), but may need to be updated for "complicated" type expressions
        if (isTypeExpression(expression) ||
            isTypeExpression(expression?.parent) ||
            isTypedArrayExpression(expression) ||
            isTypedArrayExpression(expression?.parent)) {
            return true;
        }
        if (isBinaryExpression(expression?.parent)) {
            let currentExpr: AstNode = expression.parent;
            while (isBinaryExpression(currentExpr) && currentExpr.tokens.operator.kind === TokenKind.Or) {
                currentExpr = currentExpr.parent;
            }
            return isTypeExpression(currentExpr) || isTypedArrayExpression(currentExpr);
        }
        return false;
    }

    public isGenericNodeType(type: BscType) {
        if (isComponentType(type)) {
            const lowerName = type.toString().toLowerCase();
            if (lowerName === 'rosgnode' || lowerName === 'rosgnodenode') {
                return true;
            }
        }
        return false;
    }


    public hasAnyRequiredSymbolChanged(requiredSymbols: UnresolvedSymbol[], changedSymbols: Map<SymbolTypeFlag, Set<string>>) {
        if (!requiredSymbols || !changedSymbols) {
            return false;
        }
        const runTimeChanges = changedSymbols.get(SymbolTypeFlag.runtime);
        const typeTimeChanges = changedSymbols.get(SymbolTypeFlag.typetime);

        for (const symbol of requiredSymbols) {
            if (this.setContainsUnresolvedSymbol(runTimeChanges, symbol) || this.setContainsUnresolvedSymbol(typeTimeChanges, symbol)) {
                return true;
            }
        }

        return false;
    }

    public setContainsUnresolvedSymbol(symbolLowerNameSet: Set<string>, symbol: UnresolvedSymbol) {
        if (!symbolLowerNameSet || symbolLowerNameSet.size === 0) {
            return false;
        }

        for (const possibleNameLower of symbol.lookups) {
            if (symbolLowerNameSet.has(possibleNameLower)) {
                return true;
            }
        }
        return false;
    }

    public getCustomTypesInSymbolTree(setToFill: Set<BscType>, type: BscType, filter?: (t: BscSymbol) => boolean) {
        const subSymbols = type.getMemberTable()?.getAllSymbols(SymbolTypeFlag.runtime) ?? [];
        for (const subSymbol of subSymbols) {
            if (!subSymbol.type?.isBuiltIn && !setToFill.has(subSymbol.type)) {
                if (filter && !filter(subSymbol)) {
                    continue;
                }
                // if this is a custom type, and we haven't added it to the types to check to see if can add it to the additional types
                // add the type, and investigate any members
                setToFill.add(subSymbol.type);
                this.getCustomTypesInSymbolTree(setToFill, subSymbol.type, filter);
            }

        }
    }

    public truncate<T>(options: {
        leadingText: string;
        items: T[];
        trailingText?: string;
        maxLength: number;
        itemSeparator?: string;
        partBuilder?: (item: T) => string;
    }): string {
        let leadingText = options.leadingText;
        let items = options?.items ?? [];
        let trailingText = options?.trailingText ?? '';
        let maxLength = options?.maxLength ?? 160;
        let itemSeparator = options?.itemSeparator ?? ', ';
        let partBuilder = options?.partBuilder ?? ((x) => x.toString());

        let parts = [];
        let length = leadingText.length + (trailingText?.length ?? 0);

        //calculate the max number of items we could fit in the given space
        for (let i = 0; i < items.length; i++) {
            let part = partBuilder(items[i]);
            if (i > 0) {
                part = itemSeparator + part;
            }
            parts.push(part);
            length += part.length;
            //exit the loop if we've maxed out our length
            if (length >= maxLength) {
                break;
            }
        }
        let message: string;
        //we have enough space to include all the parts
        if (parts.length >= items.length) {
            message = leadingText + parts.join('') + trailingText;

            //we require truncation
        } else {
            //account for truncation message length including max possible "more" items digits, trailing text length, and the separator between last item and trailing text
            length = leadingText.length + `...and ${items.length} more`.length + itemSeparator.length + (trailingText?.length ?? 0);
            message = leadingText;
            for (let i = 0; i < parts.length; i++) {
                //always include at least 2 items. if this part would overflow the max, then skip it and finalize the message
                if (i > 1 && length + parts[i].length > maxLength) {
                    message += itemSeparator + `...and ${items.length - i} more` + trailingText;
                    return message;
                } else {
                    message += parts[i];
                    length += parts[i].length;
                }
            }
        }
        return message;
    }

    public getAstNodeFriendlyName(node: AstNode) {
        return node?.kind.replace(/Statement|Expression/g, '');
    }


    public hasLeadingComments(input: Token | AstNode) {
        const leadingTrivia = isToken(input) ? input?.leadingTrivia : input?.leadingTrivia ?? [];
        return !!leadingTrivia.find(t => t?.kind === TokenKind.Comment);
    }

    public getLeadingComments(input: Token | AstNode) {
        const leadingTrivia = isToken(input) ? input?.leadingTrivia : input?.leadingTrivia ?? [];
        return leadingTrivia.filter(t => t?.kind === TokenKind.Comment);
    }

    public isLeadingCommentOnSameLine(line: RangeLike, input: Token | AstNode) {
        const leadingCommentRange = this.getLeadingComments(input)?.[0];
        if (leadingCommentRange) {
            return this.linesTouch(line, leadingCommentRange?.location);
        }
        return false;
    }

    public isClassUsedAsFunction(potentialClassType: BscType, expression: Expression, options: GetTypeOptions) {
        // eslint-disable-next-line no-bitwise
        if ((options?.flags ?? 0) & SymbolTypeFlag.runtime &&
            isClassType(potentialClassType) &&
            !options.isExistenceTest &&
            potentialClassType.name?.toLowerCase() === this.getAllDottedGetPartsAsString(expression)?.toLowerCase() &&
            !expression?.findAncestor(isNewExpression)) {
            return true;
        }
        return false;
    }

    public getSpecialCaseCallExpressionReturnType(callExpr: CallExpression, options: GetSymbolTypeOptions) {
        if (isVariableExpression(callExpr.callee) && callExpr.callee.tokens.name.text.toLowerCase() === 'createobject') {
            const componentName = isLiteralString(callExpr.args[0]) ? callExpr.args[0].tokens.value?.text?.replace(/"/g, '') : '';
            const nodeType = componentName.toLowerCase() === 'rosgnode' && isLiteralString(callExpr.args[1]) ? callExpr.args[1].tokens.value?.text?.replace(/"/g, '') : '';
            if (componentName?.toLowerCase().startsWith('ro')) {
                let fullName = componentName + nodeType;

                if (nodeType.includes(':')) {
                    // This node has a colon in its name, most likely from a component Library
                    // This componentType is most likely unknown, so return `roSGNode`
                    fullName = 'roSGNode';
                }

                const data = {};
                const symbolTable = callExpr.getSymbolTable();
                const foundType = symbolTable.getSymbolType(fullName, {
                    flags: SymbolTypeFlag.typetime,
                    data: data,
                    tableProvider: () => callExpr?.getSymbolTable(),
                    fullName: fullName
                });
                if (foundType) {
                    return foundType;
                }
            }
        } else if (isDottedGetExpression(callExpr.callee) &&
            callExpr.callee.tokens?.name?.text?.toLowerCase() === 'callfunc' &&
            isLiteralString(callExpr.args?.[0])) {
            return this.getCallFuncType(callExpr, callExpr.args?.[0]?.tokens.value, options);
        } else if (isDottedGetExpression(callExpr.callee) &&
            callExpr.callee.tokens?.name?.text?.toLowerCase() === 'createchild' &&
            isComponentType(callExpr.callee.obj?.getType({ flags: SymbolTypeFlag.runtime })) &&
            isLiteralString(callExpr.args?.[0])) {
            const fullName = `roSGNode${callExpr.args?.[0].tokens?.value?.text?.replace(/"/g, '')}`;
            const data = {};
            const symbolTable = callExpr.getSymbolTable();
            return symbolTable.getSymbolType(fullName, {
                flags: SymbolTypeFlag.typetime,
                data: data,
                tableProvider: () => callExpr?.getSymbolTable(),
                fullName: fullName
            });
        }
    }

    public getCallFuncType(callExpr: CallExpression | CallfuncExpression, methodNameToken: Token | Identifier, options: GetSymbolTypeOptions) {
        let result: BscType;
        let methodName = methodNameToken?.text?.replace(/"/g, ''); // remove quotes if it was the first arg of .callFunc()

        // a little hacky here with checking options.ignoreCall because callFuncExpression has the method name
        // It's nicer for CallExpression, because it's a call on any expression.
        let calleeType: BscType;
        if (isCallfuncExpression(callExpr)) {
            calleeType = callExpr.callee.getType({ ...options, flags: SymbolTypeFlag.runtime, ignoreCall: false });
        } else if (isCallExpression(callExpr) && isDottedGetExpression(callExpr.callee)) {
            calleeType = callExpr.callee.obj.getType({ ...options, flags: SymbolTypeFlag.runtime, ignoreCall: false });
        }
        const funcType = calleeType.getCallFuncType?.(methodName, options);
        if (funcType) {
            options.typeChain?.push(new TypeChainEntry({
                name: methodName,
                type: funcType,
                data: options.data,
                location: methodNameToken.location,
                separatorToken: createToken(TokenKind.Callfunc),
                astNode: callExpr
            }));
            if (options.ignoreCall) {
                result = funcType;
            } else if (isCallableType(funcType) && (!isReferenceType(funcType.returnType) || funcType.returnType.isResolvable())) {
                result = funcType.returnType;
            } else if (!isReferenceType(funcType) && (funcType as any)?.returnType?.isResolvable()) {
                result = (funcType as any).returnType;
            } else if (this.isUnionOfFunctions(funcType)) {
                result = this.getReturnTypeOfUnionOfFunctions(funcType);
            } else {
                result = new TypePropertyReferenceType(funcType, 'returnType');
            }
        }
        if (isVoidType(result)) {
            // CallFunc will always return invalid, even if function called is `as void`
            result = DynamicType.instance;
        }
        if (options.data && !options.ignoreCall) {
            options.data.isFromCallFunc = true;
        }
        return result;
    }

    public isUnionOfFunctions(type: BscType, allowReferenceTypes = false): type is UnionType {
        if (isUnionType(type)) {
            const callablesInUnion = type.types.filter(t => isCallableType(t) || (allowReferenceTypes && isReferenceType(t)));
            return callablesInUnion.length === type.types.length && callablesInUnion.length > 0;
        }
        return false;
    }

    public isIntersectionOfFunctions(type: BscType, allowReferenceTypes = false): type is IntersectionType {
        if (isIntersectionType(type)) {
            const callablesInUnion = type.types.filter(t => isCallableType(t) || (allowReferenceTypes && isReferenceType(t)));
            return callablesInUnion.length === type.types.length && callablesInUnion.length > 0;
        }
        return false;
    }

    public getFunctionTypeFromUnion(type: BscType): BscType {
        if (this.isUnionOfFunctions(type)) {
            const typedFuncsInUnion = type.types.filter(isTypedFunctionType);
            if (typedFuncsInUnion.length < type.types.length) {
                // has non-typedFuncs in union
                return FunctionType.instance;
            }
            const exampleFunc = typedFuncsInUnion[0];
            const cumulativeFunction = new TypedFunctionType(getUniqueType(typedFuncsInUnion.map(f => f.returnType), (types) => new UnionType(types)))
                .setName(exampleFunc.name)
                .setSub(exampleFunc.isSub);
            for (const param of exampleFunc.params) {
                cumulativeFunction.addParameter(param.name, param.type, param.isOptional);
            }
            return cumulativeFunction;
        }
        return undefined;
    }

    public getFunctionTypeFromIntersection(type: BscType): BscType {
        if (this.isIntersectionOfFunctions(type)) {
            const typedFuncsInUnion = type.types.filter(isTypedFunctionType);
            if (typedFuncsInUnion.length < type.types.length) {
                // has non-typedFuncs in union
                return FunctionType.instance;
            }
            const exampleFunc = typedFuncsInUnion[0];
            const cumulativeFunction = new TypedFunctionType(getUniqueType(typedFuncsInUnion.map(f => f.returnType), (types) => new IntersectionType(types)))
                .setName(exampleFunc.name)
                .setSub(exampleFunc.isSub);
            for (const param of exampleFunc.params) {
                cumulativeFunction.addParameter(param.name, param.type, param.isOptional);
            }
            return cumulativeFunction;
        }
        return undefined;
    }

    public getReturnTypeOfUnionOfFunctions(type: UnionType): BscType {
        if (this.isUnionOfFunctions(type, true)) {
            const typedFuncsInUnion = type.types.filter(t => isTypedFunctionType(t) || isReferenceType(t)) as TypedFunctionType[];
            if (typedFuncsInUnion.length < type.types.length) {
                // is non-typedFuncs in union
                return DynamicType.instance;
            }
            const funcReturns = typedFuncsInUnion.map(f => f.returnType);
            return getUniqueType(funcReturns, (types) => new UnionType(types));
        }
        return InvalidType.instance;
    }

    public getReturnTypeOfIntersectionOfFunctions(type: IntersectionType): BscType {
        if (this.isIntersectionOfFunctions(type, true)) {
            const typedFuncsInUnion = type.types.filter(t => isTypedFunctionType(t) || isReferenceType(t)) as TypedFunctionType[];
            if (typedFuncsInUnion.length < type.types.length) {
                // is non-typedFuncs in union
                return DynamicType.instance;
            }
            const funcReturns = typedFuncsInUnion.map(f => f.returnType);
            return new IntersectionType(funcReturns);//getUniqueType(funcReturns, (types) => new UnionType(types));
        }
        return InvalidType.instance;
    }

    public symbolComesFromSameNode(symbolName: string, definingNode: AstNode, symbolTable: SymbolTable) {
        let nsData: ExtraSymbolData = {};
        let foundType = symbolTable?.getSymbolType(symbolName, { flags: SymbolTypeFlag.runtime, data: nsData });
        if (foundType && definingNode === nsData?.definingNode) {
            return true;
        }
        return false;
    }

    public isCalleeMemberOfNamespace(symbolName: string, nodeWhereUsed: AstNode, namespace?: NamespaceStatement) {
        namespace = namespace ?? nodeWhereUsed.findAncestor<NamespaceStatement>(isNamespaceStatement);

        if (!this.isVariableMemberOfNamespace(symbolName, nodeWhereUsed, namespace)) {
            return false;
        }
        const exprType = nodeWhereUsed.getType({ flags: SymbolTypeFlag.runtime });

        if (isCallableType(exprType) || isClassType(exprType)) {
            return true;
        }
        return false;
    }

    public isVariableMemberOfNamespace(symbolName: string, nodeWhereUsed: AstNode, namespace?: NamespaceStatement) {
        namespace = namespace ?? nodeWhereUsed.findAncestor<NamespaceStatement>(isNamespaceStatement);
        if (!isNamespaceStatement(namespace)) {
            return false;
        }
        const namespaceParts = namespace.getNameParts();
        let namespaceType: NamespaceType;
        let symbolTable: SymbolTable = namespace.getSymbolTable();
        for (const part of namespaceParts) {
            namespaceType = symbolTable.getSymbolType(part.text, { flags: SymbolTypeFlag.runtime }) as NamespaceType;
            if (namespaceType) {
                symbolTable = namespaceType.getMemberTable();
            } else {
                return false;
            }
        }

        let varData: ExtraSymbolData = {};
        nodeWhereUsed.getType({ flags: SymbolTypeFlag.runtime, data: varData });
        const isFromSameNodeInMemberTable = this.symbolComesFromSameNode(symbolName, varData?.definingNode, namespaceType?.getMemberTable());
        return isFromSameNodeInMemberTable;
    }

    public isVariableShadowingSomething(symbolName: string, nodeWhereUsed: AstNode) {
        let varData: ExtraSymbolData = {};
        let exprType = nodeWhereUsed.getType({ flags: SymbolTypeFlag.runtime, data: varData });
        if (isReferenceType(exprType)) {
            exprType = (exprType as any).getTarget();
        }
        const namespace = nodeWhereUsed?.findAncestor<NamespaceStatement>(isNamespaceStatement);

        if (isNamespaceStatement(namespace)) {
            let namespaceHasSymbol = namespace.getSymbolTable().hasSymbol(symbolName, SymbolTypeFlag.runtime);
            // check if the namespace has a symbol with the same name, but different definiton
            if (namespaceHasSymbol && !this.symbolComesFromSameNode(symbolName, varData.definingNode, namespace.getSymbolTable())) {
                return true;
            }
        }
        const bodyTable = nodeWhereUsed.getRoot().getSymbolTable();
        const hasSymbolAtFileLevel = bodyTable.hasSymbol(symbolName, SymbolTypeFlag.runtime);
        if (hasSymbolAtFileLevel && !this.symbolComesFromSameNode(symbolName, varData.definingNode, bodyTable)) {
            return true;
        }

        return false;
    }

    public chooseTypeFromCodeOrDocComment(codeType: BscType, docType: BscType, options: GetTypeOptions) {
        let returnType: BscType;
        if (options.preferDocType && docType) {
            returnType = docType;
            if (options.data) {
                options.data.isFromDocComment = true;
            }
        } else {
            returnType = codeType;
            if (!returnType && docType) {
                returnType = docType;
                if (options.data) {
                    options.data.isFromDocComment = true;
                }
            }
        }
        return returnType;
    }

    /**
     * Gets the type for a default value (eg. as a function param, class member or typed array)
     */
    public getDefaultTypeFromValueType(valueType: (BscType | BscType[])) {
        if (!valueType) {
            return undefined;
        }
        let resultType: BscType = DynamicType.instance;
        if (Array.isArray(valueType)) {
            // passed an array opf types, potential from ArrayType.innerTypes
            if (valueType.length > 0) {
                //at least one, use it
                resultType = valueType[0];
                if (valueType?.length > 1) {
                    // more than 1, find union
                    resultType = getUniqueType(valueType, unionTypeFactory);
                }
            }
        } else {
            resultType = valueType;
        }
        if (!resultType.isResolvable()) {
            if (isUnionType(resultType)) {
                resultType = DynamicType.instance;
            } else {
                resultType = new ParamTypeFromValueReferenceType(resultType);
            }

        } else if (isEnumMemberType(resultType)) {
            // the type was an enum member... Try to get the parent enum type
            resultType = resultType.parentEnumType ?? resultType;
        } else if (isUnionType(resultType)) {
            // it was a union -- I wonder if they're resolvable now?
            const moddedTypes = resultType.types.map(t => {
                if (isEnumMemberType(t)) {
                    // the type was an enum member... Try to get the parent enum type
                    return t.parentEnumType ?? resultType;
                }
                return t;
            });
            resultType = getUniqueType(moddedTypes, unionTypeFactory);
        }
        return resultType;
    }

    /**
     * Get a short name that can be used to reference the project in logs. (typically something like `prj1`, `prj8`, etc...)
     */
    public getProjectLogName(config: { projectNumber: number }) {
        //if we have a project number, use it
        if (config?.projectNumber !== undefined) {
            return `prj${config.projectNumber}`;
        }
        //just return empty string so log functions don't crash with undefined project numbers
        return '';
    }
}

/**
 * A tagged template literal function for standardizing the path. This has to be defined as standalone function since it's a tagged template literal function,
 * we can't use `object.tag` syntax.
 */
export function standardizePath(stringParts, ...expressions: any[]) {
    let result: string[] = [];
    for (let i = 0; i < stringParts?.length; i++) {
        result.push(stringParts[i], expressions[i]);
    }
    return util.standardizePath(
        result.join('')
    );
}

/**
 * An item that can be coerced into a `Range`
 */
export type RangeLike = { location?: Location } | Location | { range?: Range } | Range | undefined;

export let util = new Util();
export default util;

rokucommunity / brighterscript / #15035

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