brighterscript 0.66.0-alpha.9 → 0.67.0

package/dist/util.d.ts

@@ -1,27 +1,25 @@
-import { type Diagnostic, type Position, type Range, type Location } from 'vscode-languageserver';
-import type { BsConfig } from './BsConfig';
-import type { CallableContainer, BsDiagnostic, FileReference, CallableContainerMap, CompilerPlugin, ExpressionInfo, TypeChainEntry, TypeChainProcessResult } from './interfaces';
+import type { Diagnostic, Position, Range, Location } from 'vscode-languageserver';
+import type { BsConfig, FinalizedBsConfig } from './BsConfig';
+import type { CallableContainer, BsDiagnostic, FileReference, CallableContainerMap, CompilerPlugin, ExpressionInfo, TranspileResult } from './interfaces';
 import { BooleanType } from './types/BooleanType';
 import { DoubleType } from './types/DoubleType';
 import { DynamicType } from './types/DynamicType';
 import { FloatType } from './types/FloatType';
+import { FunctionType } from './types/FunctionType';
 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 { ParseMode } from './parser/Parser';
 import type { DottedGetExpression, VariableExpression } from './parser/Expression';
 import type { Identifier, Locatable, Token } from './lexer/Token';
+import { CustomType } from './types/CustomType';
 import { SourceNode } from 'source-map';
+import type { 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';
+import type { Expression, Statement } from './parser/AstNode';
 export declare class Util {
     clearConsole(): void;
     /**
@@ -50,7 +48,6 @@ export declare class Util {
     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;
     /**
@@ -70,7 +67,7 @@ export declare class Util {
      * @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 collection usually a bsconfig.
@@ -89,12 +86,12 @@ export declare class Util {
      * merge with bsconfig.json and the provided options.
      * @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 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.
@@ -134,7 +131,7 @@ export declare class Util {
      * |  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
      * ```
@@ -144,28 +141,13 @@ export declare class Util {
      * |  bbb | bb   |  bbb |  b   | bbb  |    bb |  bb   |     b | a     |
      * ```
      */
-    rangesIntersectOrTouch(a: Range, b: Range): boolean;
+    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
      */
-    rangeContains(range: Range, position: Position): boolean;
-    comparePositionToRange(position: Position, range: Range): 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;
+    rangeContains(range: Range | undefined, position: Position | undefined): boolean;
+    comparePositionToRange(position: Position | undefined, range: Range | undefined): 1 | -1 | 0;
     /**
      * Parse an xml file and get back a javascript object containing its results
      */
@@ -196,11 +178,11 @@ export declare class Util {
     /**
      * Get the outDir from options, taking into account cwd and absolute outFile paths
      */
-    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 typedef path, so return undefined for everything else
@@ -213,7 +195,7 @@ export declare class Util {
     /**
      * 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 the minimum number of milliseconds to sleep for
@@ -224,7 +206,7 @@ export declare class Util {
      * @param array the array to flatMap over
      * @param callback a function that is called for every array item
      */
-    flatMap<T, R>(array: T[], callback: (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
@@ -252,9 +234,9 @@ export declare class Util {
      * If the two items have lines that touch
      */
     linesTouch(first: {
-        range: Range;
+        range?: Range | undefined;
     }, second: {
-        range: Range;
+        range?: Range | undefined;
     }): boolean;
     /**
      * Given text with (or without) dots separating text, get the rightmost word.
@@ -264,7 +246,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.
@@ -278,11 +260,6 @@ export declare class Util {
      * 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
      */
@@ -297,16 +274,14 @@ export declare class Util {
      */
     createBoundingRange(...locatables: Array<{
         range?: Range;
-    }>): Range;
-    /**
-     * 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;
+    } | null | undefined>): Range | undefined;
     /**
      * Create a `Position` object. Prefer this over `Position.create` for performance reasons
      */
-    createPosition(line: number, character: number): Position;
+    createPosition(line: number, character: number): {
+        line: number;
+        character: number;
+    };
     /**
      * Convert a list of tokens into a string, including their leading whitespace
      */
@@ -314,27 +289,10 @@ export declare class Util {
     /**
      * Convert a token into a BscType
      */
-    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;
+    tokenToBscType(token: Token, allowCustomType?: boolean): DynamicType | BooleanType | LongIntegerType | IntegerType | FloatType | DoubleType | FunctionType | InvalidType | ObjectType | StringType | VoidType | CustomType;
     /**
      * 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;
     /**
@@ -345,33 +303,30 @@ export declare class Util {
      * 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[];
+    getExpressionInfo(expression: Expression, file: BrsFile): ExpressionInfo;
     /**
      * 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 shouldn't ever get changed directly)
+     */
+    cloneSGAttribute(attr: SGAttribute, value: string): SGAttribute;
     /**
      * 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, bslibDestinationDir?: string): Promise<void>;
     /**
      * 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
      */
-    toDiagnostic(diagnostic: Diagnostic | BsDiagnostic, relatedInformationFallbackLocation: string): {
-        severity: import("vscode-languageserver").DiagnosticSeverity;
-        range: Range;
-        message: string;
-        relatedInformation: {
-            location: Location;
-            message: string;
-        }[];
-        code: string | number;
-        source: string;
-    };
+    toDiagnostic(diagnostic: Diagnostic | BsDiagnostic, relatedInformationFallbackLocation: string): Diagnostic;
     /**
      * Get the first locatable item found at the specified position
      * @param locatables an array of items that have a `range` property
@@ -399,13 +354,7 @@ export declare class Util {
      * @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(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;
+    getAllDottedGetParts(node: Expression | Statement): Identifier[] | undefined;
     /**
      * Break an expression into each part.
      */
@@ -424,20 +373,10 @@ export declare class Util {
     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;
+     * Wraps SourceNode's constructor to be compatible with the TranspileResult type
+     */
+    sourceNodeFromTranspileResult(line: number | null, column: number | null, source: string | null, chunks?: string | SourceNode | TranspileResult, name?: string): SourceNode;
+    isBuiltInType(typeName: string): any;
 }
 /**
  * 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,