brighterscript 1.0.0-alpha.23 → 1.0.0-alpha.25

package/dist/util.d.ts

@@ -1,31 +1,39 @@
-import type { Diagnostic, Position, Range } from 'vscode-languageserver';
-import type { BsConfig } from './BsConfig';
-import type { CallableContainer, BsDiagnostic, FileReference, CallableContainerMap, CompilerPlugin, ExpressionInfo, FunctionCall, CallableParam, TranspileResult } from './interfaces';
+import { type Diagnostic, type Position, type Range, type Location } from 'vscode-languageserver';
+import type { BsConfig, FinalizedBsConfig } from './BsConfig';
+import type { CallableContainer, BsDiagnostic, FileReference, CallableContainerMap, CompilerPlugin, ExpressionInfo, TypeChainEntry, TypeChainProcessResult } 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 { InvalidType } from './types/InvalidType';
 import { LongIntegerType } from './types/LongIntegerType';
+import { ObjectType } from './types/ObjectType';
 import { StringType } from './types/StringType';
 import { VoidType } from './types/VoidType';
-import type { DottedGetExpression, Expression, NamespacedVariableNameExpression, VariableExpression } from './parser/Expression';
+import { ParseMode } from './parser/Parser';
+import type { DottedGetExpression, VariableExpression } from './parser/Expression';
 import type { Identifier, Locatable, Token } from './lexer/Token';
 import { SourceNode } from 'source-map';
-import { SGAttribute } from './parser/SGTypes';
+import type { BrsFile } from './files/BrsFile';
+import type { XmlFile } from './files/XmlFile';
+import type { AstNode } from './parser/AstNode';
+import { type Expression, type Statement } from './parser/AstNode';
 import type { BscType } from './types/BscType';
 import { FunctionType } from './types/FunctionType';
+import type { SymbolTable } from './SymbolTable';
+import type { UnresolvedSymbol } from './AstValidationSegmenter';
 export declare class Util {
     clearConsole(): void;
+    /**
+     * Returns the number of parent directories in the filPath
+     */
+    getParentDirectoryCount(filePath: string | undefined): number;
     /**
      * Determine if the file exists
-     * @param filePath
      */
     pathExists(filePath: string | undefined): Promise<boolean>;
     /**
      * Determine if the file exists
-     * @param filePath
      */
     pathExistsSync(filePath: string | undefined): boolean;
     /**
@@ -40,77 +48,73 @@ export declare class Util {
      * Determine if the given path starts with a protocol
      */
     startsWithProtocol(path: string): boolean;
+    /**
+     * Given a pkg path of any kind, transform it to a roku-specific pkg path (i.e. "pkg:/some/path.brs")
+     * @deprecated use `sanitizePkgPath instead. Will be removed in v1
+     */
+    getRokuPkgPath(pkgPath: string): string;
     /**
      * Given a path to a file/directory, replace all path separators with the current system's version.
-     * @param filePath
      */
     pathSepNormalize(filePath: string, separator?: string): string;
     /**
      * Find the path to the config file.
      * If the config file path doesn't exist
-     * @param configFilePath
+     * @param cwd the current working directory where the search for configs should begin
      */
     getConfigFilePath(cwd?: string): string;
     getRangeFromOffsetLength(text: string, offset: number, length: number): Range;
     /**
      * Load the contents of a config file.
      * If the file extends another config, this will load the base config as well.
-     * @param configFilePath
-     * @param parentProjectPaths
+     * @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
      */
-    loadConfigFile(configFilePath: string, parentProjectPaths?: string[], cwd?: string): BsConfig;
+    loadConfigFile(configFilePath: string | undefined, parentProjectPaths?: string[], cwd?: string): BsConfig | undefined;
     /**
      * Convert relative paths to absolute paths, relative to the given directory. Also de-dupes the paths. Modifies the array in-place
-     * @param paths the list of paths to be resolved and deduped
+     * @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
      */
     resolvePathsRelativeTo(collection: any, key: string, relativeDir: string): void;
     /**
      * Do work within the scope of a changed current working directory
-     * @param targetCwd
-     * @param callback
+     * @param targetCwd the cwd where the work should be performed
+     * @param callback a function to call when the cwd has been changed to `targetCwd`
      */
     cwdWork<T>(targetCwd: string | null | undefined, callback: () => T): T;
     /**
      * Given a BsConfig object, start with defaults,
      * merge with bsconfig.json and the provided options.
-     * @param config
+     * @param config a bsconfig object to use as the baseline for the resulting config
      */
-    normalizeAndResolveConfig(config: BsConfig): BsConfig;
+    normalizeAndResolveConfig(config: BsConfig | undefined): FinalizedBsConfig;
     /**
      * Set defaults for any missing items
-     * @param config
+     * @param config a bsconfig object to use as the baseline for the resulting config
      */
-    normalizeConfig(config: BsConfig): BsConfig;
+    normalizeConfig(config: BsConfig | undefined): FinalizedBsConfig;
     /**
      * Get the root directory from options.
      * Falls back to options.cwd.
      * Falls back to process.cwd
-     * @param options
+     * @param options a bsconfig object
      */
     getRootDir(options: BsConfig): string;
-    /**
-     * Format a string with placeholders replaced by argument indexes
-     * @param subject
-     * @param params
-     */
-    stringFormat(subject: string, ...args: any[]): string;
     /**
      * Given a list of callables as a dictionary indexed by their full name (namespace included, transpiled to underscore-separated.
-     * @param callables
      */
     getCallableContainersByLowerName(callables: CallableContainer[]): CallableContainerMap;
     /**
      * Split a file by newline characters (LF or CRLF)
-     * @param text
      */
     getLines(text: string): string[];
     /**
-     * Compute the pkg path for the target relative to the source file's location
-     * @param sourcePkgPath The pkgPath of the file that contains the target path
-     * @param targetPath a full pkgPath, or a path relative to the containing file
+     * 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
      */
-    getPkgPathFromTarget(sourcePkgPath: string, targetPath: string): string;
+    getPkgPathFromTarget(containingFilePathAbsolute: string, targetPath: string): string;
     /**
      * 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
@@ -122,34 +126,64 @@ export declare class Util {
      */
     findBeginningVariableExpression(dottedGet: DottedGetExpression): VariableExpression | undefined;
     /**
-     * Does a touch b in any way?
+     * 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     |
+     * ```
      */
-    rangesIntersect(a: Range, b: Range): boolean;
+    rangesIntersect(a: Range | undefined, b: Range | undefined): boolean;
+    /**
+     * 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     |
+     * ```
+     */
+    rangesIntersectOrTouch(a: Range | undefined, b: Range | undefined): boolean;
     /**
      * Test if `position` is in `range`. If the position is at the edges, will return true.
      * Adapted from core vscode
-     * @param range
-     * @param position
      */
-    rangeContains(range: Range, position: Position): boolean;
-    comparePositionToRange(position: Position, range: Range): 1 | -1 | 0;
+    rangeContains(range: Range | undefined, position: Position | undefined): boolean;
+    comparePositionToRange(position: Position | undefined, range: Range | undefined): 1 | -1 | 0;
+    /**
+     * Combine all the documentation found before a token (i.e. comment tokens)
+     */
+    getTokenDocumentation(tokens: Token[], token?: Token): string;
+    /**
+     * Combine all the documentation for a node - uses the AstNode's leadingTrivia property
+     */
+    getNodeDocumentation(node: AstNode): string;
+    /**
+     * 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`
+     */
+    getSgNodeTypeName(sgNodeName: string): string;
     /**
      * Parse an xml file and get back a javascript object containing its results
-     * @param text
      */
     parseXml(text: string): Promise<any>;
     propertyCount(object: Record<string, unknown>): number;
     padLeft(subject: string, totalLength: number, char: string): string;
     /**
      * Given a URI, convert that to a regular fs path
-     * @param uri
      */
     uriToPath(uri: string): string;
     /**
      * Force the drive letter to lower case
-     * @param fullPath
      */
     driveLetterToLower(fullPath: string): string;
+    /**
+     * Replace the first instance of `search` in `subject` with `replacement`
+     */
+    replaceCaseInsensitive(subject: string, search: string, replacement: string): string;
     /**
      * Determine if two arrays containing primitive values are equal.
      * This considers order and compares by equality.
@@ -157,45 +191,40 @@ export declare class Util {
     areArraysEqual(arr1: any[], arr2: any[]): boolean;
     /**
      * Given a file path, convert it to a URI string
-     * @param srcPath The absolute path to the source file on disk
      */
-    pathToUri(srcPath: string): string;
+    pathToUri(filePath: string): string;
     /**
      * Get the outDir from options, taking into account cwd and absolute outFile paths
-     * @param options
      */
-    getOutDir(options: BsConfig): string;
+    getOutDir(options: FinalizedBsConfig): string;
     /**
      * Get paths to all files on disc that match this project's source list
      */
-    getFilePaths(options: BsConfig): Promise<import("roku-deploy").StandardizedFileEntry[]>;
+    getFilePaths(options: FinalizedBsConfig): Promise<import("roku-deploy").StandardizedFileEntry[]>;
     /**
      * Given a path to a brs file, compute the path to a theoretical d.bs file.
-     * Only `.brs` files can have a typedef, so return undefined for everything else
-     * @param brsSrcPath The absolute path to the .brs source file on disk
+     * Only `.brs` files can have typedef path, so return undefined for everything else
      */
     getTypedefPath(brsSrcPath: string): string;
     /**
      * Determine whether this diagnostic should be supressed or not, based on brs comment-flags
-     * @param diagnostic
      */
     diagnosticIsSuppressed(diagnostic: BsDiagnostic): boolean;
     /**
-     * Walks up the chain
-     * @param currentPath
+     * Walks up the chain to find the closest bsconfig.json file
      */
-    findClosestConfigFile(currentPath: string): Promise<string>;
+    findClosestConfigFile(currentPath: string): Promise<string | undefined>;
     /**
      * Set a timeout for the specified milliseconds, and resolve the promise once the timeout is finished.
-     * @param milliseconds
+     * @param milliseconds the minimum number of milliseconds to sleep for
      */
     sleep(milliseconds: number): Promise<unknown>;
     /**
      * Given an array, map and then flatten
-     * @param arr
-     * @param cb
+     * @param array the array to flatMap over
+     * @param callback a function that is called for every array item
      */
-    flatMap<T, R>(array: T[], cb: (arg: T) => R): R;
+    flatMap<T, R>(array: T[], callback: (arg: T) => R[]): R[];
     /**
      * 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
@@ -221,8 +250,6 @@ export declare class Util {
     }): boolean;
     /**
      * If the two items have lines that touch
-     * @param first
-     * @param second
      */
     linesTouch(first: {
         range: Range;
@@ -237,7 +264,7 @@ export declare class Util {
     /**
      * Find a script import that the current position touches, or undefined if not found
      */
-    getScriptImportAtPosition(scriptImports: FileReference[], position: Position): FileReference;
+    getScriptImportAtPosition(scriptImports: FileReference[], position: Position): FileReference | undefined;
     /**
      * 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.
@@ -248,7 +275,16 @@ export declare class Util {
     splitIntoLines(string: string): string[];
     getTextForRange(string: string | string[], range: Range): string;
     /**
-     * Helper for creating `Range` objects. Prefer using this function because vscode-languageserver's `util.createRange()` is significantly slower
+     * Helper for creating `Location` objects. Prefer using this function because vscode-languageserver's `Location.create()` is significantly slower at scale
+     */
+    createLocation(uri: string, range: Range): Location;
+    /**
+     * A cache of `Range` objects. The key is a 52bit integer created from the 4 range integers and leveraging bitshifting.
+     * The whole point of this cache is to reduce garbage collection churn, so we didn't want to use string concatenation for the key
+     */
+    private rangeCache;
+    /**
+     * Helper for creating `Range` objects. Prefer using this function because vscode-languageserver's `Range.create()` is significantly slower
      */
     createRange(startLine: number, startCharacter: number, endLine: number, endCharacter: number): Range;
     /**
@@ -261,14 +297,16 @@ export declare class Util {
      */
     createBoundingRange(...locatables: Array<{
         range?: Range;
-    }>): Range;
+    }>): Range | undefined;
+    /**
+     * A cache of `Position` objects. The key is a 26bit integer created from line and character and leveraging bitshifting
+     * The whole point of this cache is to reduce garbage collection churn, so we didn't want to use string concatenation for the key
+     */
+    private positionCache;
     /**
      * Create a `Position` object. Prefer this over `Position.create` for performance reasons
      */
-    createPosition(line: number, character: number): {
-        line: number;
-        character: number;
-    };
+    createPosition(line: number, character: number): Position;
     /**
      * Convert a list of tokens into a string, including their leading whitespace
      */
@@ -276,88 +314,64 @@ export declare class Util {
     /**
      * Convert a token into a BscType
      */
-    tokenToBscType(token: Token, allowBrighterscriptTypes?: boolean, currentNamespaceName?: NamespacedVariableNameExpression): DynamicType | BscType | FloatType | IntegerType | DoubleType | LongIntegerType | StringType | BooleanType | FunctionType | InvalidType | VoidType;
+    tokenToBscType(token: Token): DynamicType | ObjectType | StringType | IntegerType | BooleanType | FloatType | DoubleType | LongIntegerType | VoidType | FunctionType;
+    /**
+     * 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
+     */
+    getNodeFieldType(typeDescriptor: string, lookupTable?: SymbolTable): BscType;
+    /**
+     * 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
+     */
+    binaryOperatorResultType(leftType: BscType, operator: Token, rightType: BscType): BscType;
+    /**
+     * Return the type of the result of a binary operator
+     */
+    unaryOperatorResultType(operator: Token, exprType: BscType): BscType;
     /**
      * 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...)
      */
     getExtension(filePath: string): string;
     /**
      * Load and return the list of plugins
      */
     loadPlugins(cwd: string, pathOrModules: string[], onError?: (pathOrModule: string, err: Error) => void): CompilerPlugin[];
-    resolveRequire(cwd: string, pathOrModule: string): any;
     /**
      * Gathers expressions, variables, and unique names from an expression.
      * This is mostly used for the ternary expression
      */
     getExpressionInfo(expression: Expression): ExpressionInfo;
+    concatAnnotationLeadingTrivia(stmt: Statement, otherTrivia: Token[]): Token[];
     /**
      * 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
      */
     simpleMap(source: string, src: string): SourceNode;
-    /**
-     * Creates a new SGAttribute object, but keeps the existing Range references (since those should be immutable)
-     */
-    cloneSGAttribute(attr: SGAttribute, value: string): SGAttribute;
-    /**
-     * Shorthand for creating a new source node
-     */
-    sourceNode(source: string, locatable: {
-        range: Range;
-    }, code: string | SourceNode | TranspileResult): SourceNode | undefined;
-    /**
-     * Remove leading simple protocols from a path (if present)
-     */
-    removeProtocol(pkgPath: string): string;
     /**
      * Converts a path into a standardized format (drive letter to lower, remove extra slashes, use single slash type, resolve relative parts, etc...)
      */
     standardizePath(thePath: string): string;
     /**
-     * Copy the version of bslib from local node_modules to the staging folder
-     */
-    copyBslibToStaging(stagingDir: string): Promise<void>;
-    /**
-     * Given a Diagnostic or BsDiagnostic, return a copy of the diagnostic
-     */
-    toDiagnostic(diagnostic: Diagnostic | BsDiagnostic): {
-        severity: import("vscode-languageserver-types").DiagnosticSeverity;
-        range: Range;
-        message: string;
-        relatedInformation: {
-            location: import("vscode-languageserver-types").Location;
-            message: string;
-        }[];
-        code: string | number;
-        source: string;
-    };
-    /**
-     * Gets the minimum and maximum number of allowed params
-     * @param params The list of callable parameters to check
-     * @returns the minimum and maximum number of allowed params
-     */
-    getMinMaxParamCount(params: CallableParam[]): MinMax;
-    /**
-     * Gets the minimum and maximum number of allowed params for ALL functions with the name of the function call
-     * @param callablesByLowerName The map of callable containers
-     * @param expCall function call expression to use for the name
-     * @returns the minimum and maximum number of allowed params
+     * 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
      */
-    getMinMaxParamCountByFunctionCall(callablesByLowerName: CallableContainerMap, expCall: FunctionCall): MinMax;
+    toDiagnostic(diagnostic: Diagnostic | BsDiagnostic, relatedInformationFallbackLocation: string): Diagnostic;
     /**
-     * Finds the array of callables from a container map, based on the name of the function call
-     * If the callable was called in a function in a namespace, functions in that namespace are preferred
-     * @param callablesByLowerName The map of callable containers
-     * @param expCall function call expression to use for the name
-     * @return an array with callable containers - could be empty if nothing was found
+     * Get the first locatable item found at the specified position
+     * @param locatables an array of items that have a `range` property
+     * @param position the position that the locatable must contain
      */
-    getCallableContainersByName(callablesByLowerName: CallableContainerMap, expCall: FunctionCall): CallableContainer[];
+    getFirstLocatableAt(locatables: Locatable[], position: Position): Locatable;
     /**
      * Sort an array of objects that have a Range
      */
-    sortByRange(locatables: Locatable[]): Locatable[];
+    sortByRange<T extends Locatable>(locatables: T[]): T[];
     /**
      * Split the given text and return ranges for each chunk.
      * Only works for single-line strings
@@ -366,20 +380,30 @@ export declare class Util {
         text: string;
         range: Range;
     }[];
-    mdFence(code: string, language?: string): string;
     /**
-     * Finds a callable from a container map based on the name AND number of arguments
-     * If the callable was called in a function in a namespace, functions in that namespace are preferred
-     * The first callable that matches the name AND will accept the number of arguments given is returned
-     * @return a callable containers that matches the call
+     * Wrap the given code in a markdown code fence (with the language)
      */
-    getCallableContainerByFunctionCall(callablesByLowerName: CallableContainerMap, expCall: FunctionCall): CallableContainer;
+    mdFence(code: string, language?: string): string;
     /**
      * Gets each part of the dotted get.
-     * @param expression
+     * @param node any ast expression
      * @returns an array of the parts of the dotted get. If not fully a dotted get, then returns undefined
      */
-    getAllDottedGetParts(expression: Expression): Identifier[] | undefined;
+    getAllDottedGetParts(node: AstNode): Identifier[] | undefined;
+    /**
+     * Given an expression, return all the DottedGet name parts as a string.
+     * Mostly used to convert namespaced item full names to a strings
+     */
+    getAllDottedGetPartsAsString(node: Expression | Statement, parseMode?: ParseMode): string;
+    stringJoin(strings: string[], separator: string): string;
+    /**
+     * Break an expression into each part.
+     */
+    splitExpression(expression: Expression): Expression[];
+    /**
+     * Break an expression into each part, and return any VariableExpression or DottedGet expresisons from left-to-right.
+     */
+    getDottedGetPath(expression: Expression): [VariableExpression, ...DottedGetExpression[]];
     /**
      * Returns an integer if valid, or undefined. Eliminates checking for NaN
      */
@@ -388,6 +412,23 @@ export declare class Util {
      * Converts a range to a string in the format 1:2-3:4
      */
     rangeToString(range: Range): string;
+    validateTooDeepFile(file: (BrsFile | XmlFile)): void;
+    /**
+     * Find the index of the last item in the array that matches.
+     */
+    findLastIndex<T>(array: T[], matcher: (T: any) => boolean): number;
+    processTypeChain(typeChain: TypeChainEntry[]): TypeChainProcessResult;
+    isInTypeExpression(expression: AstNode): boolean;
+    setContainsUnresolvedSymbol(symbolLowerNameSet: Set<string>, symbol: UnresolvedSymbol): boolean;
+    truncate<T>(options: {
+        leadingText: string;
+        items: T[];
+        trailingText?: string;
+        maxLength: number;
+        itemSeparator?: string;
+        partBuilder?: (item: T) => string;
+    }): string;
+    getAstNodeFriendlyName(node: AstNode): string;
 }
 /**
  * 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,
@@ -396,8 +437,3 @@ export declare class Util {
 export declare function standardizePath(stringParts: any, ...expressions: any[]): string;
 export declare let util: Util;
 export default util;
-export interface MinMax {
-    min: number;
-    max: number;
-}
-export declare const MAX_PARAM_COUNT = 32;