brighterscript 0.66.0-alpha.6 → 0.66.0-alpha.8

package/dist/Program.d.ts

@@ -1,24 +1,18 @@
 import type { CodeAction, Position, Range, SignatureInformation, Location } from 'vscode-languageserver';
 import type { BsConfig } from './BsConfig';
 import { Scope } from './Scope';
-import { BrsFile } from './files/BrsFile';
-import { XmlFile } from './files/XmlFile';
-import type { BsDiagnostic, File, FileObj, BscFile, SemanticToken, FileLink, Hover } from './interfaces';
+import type { BrsFile, ProvidedSymbolInfo } from './files/BrsFile';
+import type { XmlFile } from './files/XmlFile';
+import type { BsDiagnostic, FileObj, SemanticToken, FileLink, Hover } from './interfaces';
+import type { File } from './files/File';
 import { XmlScope } from './XmlScope';
 import { Logger } from './Logger';
 import PluginInterface from './PluginInterface';
 import type { FunctionStatement } from './parser/Statement';
-import type { SourceMapGenerator } from 'source-map';
+import { Editor } from './astUtils/Editor';
 import type { Statement } from './parser/AstNode';
-export interface SourceObj {
-    srcPath: string;
-    source: string;
-    definitions?: string;
-}
-export interface TranspileObj {
-    file: BscFile;
-    outputPath: string;
-}
+import type { FileData } from './files/LazyFileData';
+import type { UnresolvedSymbol } from './AstValidationSegmenter';
 export interface SignatureInfoObj {
     index: number;
     key: string;
@@ -35,6 +29,14 @@ export declare class Program {
      */
     options: BsConfig, logger?: Logger, plugins?: PluginInterface);
     logger: Logger;
+    /**
+     * An editor that plugins can use to modify program-level things during the build flow. Don't use this to edit files (they have their own `.editor`)
+     */
+    editor: Editor;
+    /**
+     * A factory that creates `File` instances
+     */
+    private fileFactory;
     private createGlobalScope;
     private recursivelyAddNodeToSymbolTable;
     /**
@@ -64,6 +66,12 @@ export declare class Program {
      * Should only be set from `this.validate()`
      */
     private diagnostics;
+    private fileSymbolInformation;
+    addFileSymbolInfo(file: BrsFile): void;
+    getFileSymbolInfo(file: BrsFile): {
+        provides: ProvidedSymbolInfo;
+        requires: UnresolvedSymbol[];
+    };
     /**
      * The path to bslib.brs (the BrightScript runtime for certain BrighterScript features)
      */
@@ -72,8 +80,17 @@ export declare class Program {
     /**
      * A map of every file loaded into this program, indexed by its original file location
      */
-    files: Record<string, BscFile>;
-    private pkgMap;
+    files: Record<string, File>;
+    /**
+     * A map of every file loaded into this program, indexed by its destPath
+     */
+    private destMap;
+    /**
+     * Plugins can contribute multiple virtual files for a single physical file.
+     * This collection links the virtual files back to the physical file that produced them.
+     * The key is the standardized and lower-cased srcPath
+     */
+    private fileClusters;
     private scopes;
     protected addScope(scope: Scope): void;
     /**
@@ -137,9 +154,9 @@ export declare class Program {
      * @param normalizePath should the provided path be normalized before use
      */
     hasFile(filePath: string, normalizePath?: boolean): boolean;
-    getPkgPath(...args: any[]): any;
     /**
      * roku filesystem is case INsensitive, so find the scope by key case insensitive
+     * @param scopeName xml scope names are their `destPath`. Source scope is stored with the key `"source"`
      */
     getScopeByName(scopeName: string): Scope;
     /**
@@ -162,17 +179,17 @@ export declare class Program {
      * Load a file into the program. If that file already exists, it is replaced.
      * If file contents are provided, those are used, Otherwise, the file is loaded from the file system
      * @param srcDestOrPkgPath the absolute path, the pkg path (i.e. `pkg:/path/to/file.brs`), or the destPath (i.e. `path/to/file.brs` relative to `pkg:/`)
-     * @param fileContents the file contents
+     * @param fileData the file contents. omit or pass `undefined` to prevent loading the data at this time
      */
-    setFile<T extends BscFile>(srcDestOrPkgPath: string, fileContents: string): T;
+    setFile<T extends File>(srcDestOrPkgPath: string, fileData?: FileData): T;
     /**
      * Load a file into the program. If that file already exists, it is replaced.
      * @param fileEntry an object that specifies src and dest for the file.
-     * @param fileContents the file contents. If not provided, the file will be loaded from disk
+     * @param fileData the file contents. omit or pass `undefined` to prevent loading the data at this time
      */
-    setFile<T extends BscFile>(fileEntry: FileObj, fileContents: string): T;
+    setFile<T extends File>(fileEntry: FileObj, fileData: FileData): T;
     /**
-     * Given a srcPath, a pkgPath, or both, resolve whichever is missing, relative to rootDir.
+     * Given a srcPath, a destPath, or both, resolve whichever is missing, relative to rootDir.
      * @param fileParam an object representing file paths
      * @param rootDir must be a pre-normalized path
      */
@@ -181,6 +198,14 @@ export declare class Program {
      * Remove any leading `pkg:/` found in the path
      */
     private removePkgPrefix;
+    /**
+     * Is this file a .brs file found somewhere within the `pkg:/source/` folder?
+     */
+    private isSourceBrsFile;
+    /**
+     * Is this file a .brs file found somewhere within the `pkg:/source/` folder?
+     */
+    private isComponentsXmlFile;
     /**
      * Ensure source scope is created.
      * Note: automatically called internally, and no-op if it exists already.
@@ -194,14 +219,29 @@ export declare class Program {
     removeFiles(srcPaths: string[], normalizePath?: boolean): void;
     /**
      * Remove a file from the program
-     * @param filePath can be a srcPath, a pkgPath, or a destPath (same as pkgPath but without `pkg:/`)
+     * @param filePath can be a srcPath, a destPath, or a destPath with leading `pkg:/`
      * @param normalizePath should this function repair and standardize the path? Passing false should have a performance boost if you can guarantee your path is already sanitized
      */
-    removeFile(filePath: string, normalizePath?: boolean): void;
+    removeFile(filePath: string, normalizePath?: boolean, keepSymbolInformation?: boolean): void;
+    lastValidationInfo: Map<string, {
+        symbolsNotDefinedInEveryScope: {
+            symbol: UnresolvedSymbol;
+            scope: Scope;
+        }[];
+        duplicateSymbolsInSameScope: {
+            symbol: UnresolvedSymbol;
+            scope: Scope;
+        }[];
+        symbolsNotConsistentAcrossScopes: {
+            symbol: UnresolvedSymbol;
+            scopes: Scope[];
+        }[];
+    }>;
     /**
      * Traverse the entire project, and validate all scopes
      */
     validate(): void;
+    private detectIncompatibleSymbolsAcrossScopes;
     /**
      * Flag all duplicate component names
      */
@@ -211,22 +251,22 @@ export declare class Program {
      * @param filePaths can be an array of srcPath or a destPath strings
      * @param normalizePath should this function repair and standardize the paths? Passing false should have a performance boost if you can guarantee your paths are already sanitized
      */
-    getFiles<T extends BscFile>(filePaths: string[], normalizePath?: boolean): T[];
+    getFiles<T extends File>(filePaths: string[], normalizePath?: boolean): T[];
     /**
      * Get the file at the given path
      * @param filePath can be a srcPath or a destPath
      * @param normalizePath should this function repair and standardize the path? Passing false should have a performance boost if you can guarantee your path is already sanitized
      */
-    getFile<T extends BscFile>(filePath: string, normalizePath?: boolean): T;
+    getFile<T extends File>(filePath: string, normalizePath?: boolean): T;
     /**
      * Get a list of all scopes the file is loaded into
      * @param file the file
      */
-    getScopesForFile(file: XmlFile | BrsFile | string): Scope[];
+    getScopesForFile(file: File | string): Scope[];
     /**
      * Get the first found scope for a file.
      */
-    getFirstScopeForFile(file: XmlFile | BrsFile): Scope;
+    getFirstScopeForFile(file: File): Scope;
     getStatementsByName(name: string, originFile: BrsFile, namespaceName?: string): FileLink<Statement>[];
     getStatementsForXmlFile(scope: XmlScope, filterName?: string): FileLink<FunctionStatement>[];
     /**
@@ -267,24 +307,41 @@ export declare class Program {
      * @param filePath can be a srcPath or a destPath
      */
     getTranspiledFileContents(filePath: string): Promise<FileTranspileResult>;
+    private getTranspiledFileContentsPipeline;
+    /**
+     * Get the absolute output path for a file
+     */
+    private getOutputPath;
+    private getStagingDir;
+    /**
+     * Prepare the program for building
+     * @param files the list of files that should be prepared
+     */
+    private prepare;
+    /**
+     * Generate the contents of every file
+     */
+    private serialize;
     /**
-     * Internal function used to transpile files.
-     * This does not write anything to the file system
+     * Write the entire project to disk
      */
-    private _getTranspiledFileContents;
-    private beforeProgramTranspile;
-    transpile(fileEntries: FileObj[], stagingDir: string): Promise<void>;
-    private afterProgramTranspile;
+    private write;
+    private buildPipeline;
+    /**
+     * Build the project. This transpiles/transforms/copies all files and moves them to the staging directory
+     * @param options the list of options used to build the program
+     */
+    build(options?: ProgramBuildOptions): Promise<void>;
     /**
      * Find a list of files in the program that have a function with the given name (case INsensitive)
      */
-    findFilesForFunction(functionName: string): BscFile[];
+    findFilesForFunction(functionName: string): File[];
     /**
      * Find a list of files in the program that have a class with the given name (case INsensitive)
      */
-    findFilesForClass(className: string): BscFile[];
-    findFilesForNamespace(name: string): BscFile[];
-    findFilesForEnum(name: string): BscFile[];
+    findFilesForClass(className: string): File[];
+    findFilesForNamespace(name: string): File[];
+    findFilesForEnum(name: string): File[];
     /**
      * Get a map of the manifest information
      */
@@ -294,8 +351,20 @@ export declare class Program {
 }
 export interface FileTranspileResult {
     srcPath: string;
+    destPath: string;
     pkgPath: string;
     code: string;
-    map: SourceMapGenerator;
+    map: string;
     typedef: string;
 }
+export interface ProgramBuildOptions {
+    /**
+     * The directory where the final built files should be placed. This directory will be cleared before running
+     */
+    stagingDir?: string;
+    /**
+     * An array of files to build. If omitted, the entire list of files from the program will be used instead.
+     * Typically you will want to leave this blank
+     */
+    files?: File[];
+}