brighterscript 1.0.0-alpha.3 → 1.0.0-alpha.31

package/README.md

@@ -1,18 +1,22 @@
-# BrighterScript [v1 branch]
+# BrighterScript
 
 A superset of Roku's BrightScript language. Compiles to standard BrightScript.
 
-[![build](https://img.shields.io/github/workflow/status/rokucommunity/brighterscript/build.svg?logo=github)](https://github.com/rokucommunity/brighterscript/actions?query=workflow%3Abuild)
-[![Coverage Status](https://coveralls.io/repos/github/rokucommunity/brighterscript/badge.svg?branch=master)](https://coveralls.io/github/rokucommunity/brighterscript?branch=master)
-[![NPM Version](https://badge.fury.io/js/brighterscript.svg?style=flat)](https://npmjs.org/package/brighterscript)
+[![build status](https://img.shields.io/github/actions/workflow/status/rokucommunity/brighterscript/build.yml?branch=master&logo=github)](https://github.com/rokucommunity/brighterscript/actions?query=branch%3Amaster+workflow%3Abuild)
+[![coverage status](https://img.shields.io/coveralls/github/rokucommunity/brighterscript?logo=coveralls)](https://coveralls.io/github/rokucommunity/brighterscript?branch=master)
+[![monthly downloads](https://img.shields.io/npm/dm/brighterscript.svg?sanitize=true&logo=npm&logoColor=)](https://npmcharts.com/compare/brighterscript?minimal=true)
+[![npm version](https://img.shields.io/npm/v/brighterscript.svg?logo=npm)](https://www.npmjs.com/package/brighterscript)
+[![license](https://img.shields.io/npm/l/brighterscript.svg)](LICENSE)
+[![Slack](https://img.shields.io/badge/Slack-RokuCommunity-4A154B?logo=slack)](https://join.slack.com/t/rokudevelopers/shared_invite/zt-4vw7rg6v-NH46oY7hTktpRIBM_zGvwA)
 
-This is the v1 branch. Unless you're specifically looking for v1, you probably want to view [the master branch](https://github.com/rokucommunity/brighterscript).
 ## Overview
 
+**WARNING: this is the v0.66.0 branch with experimental features**
+
 The BrighterScript language provides new features and syntax enhancements to Roku's BrightScript language. Because the language is a superset of BrightScript, the parser and associated tools (VSCode integration, cli, etc...) work with standard BrightScript (.brs) files. This means you will get benefits (as described in the following section) from using the BrighterScript compiler, whether your project contains BrighterScript (.bs) files or not. The BrighterScript language transpiles to standard BrightScript, so your code is fully compatible with all roku devices.
 
 ## Features
-BrighterScript adds several new features to the BrightScript language such as Namespaces, classes, import statements, and more. Take a look at the language specification docs for more information.
+BrighterScript adds several new features to the BrightScript language such as namespaces, classes, import statements, and more. Take a look at the language specification docs for more information.
 
 [BrighterScript Language Specification](https://github.com/rokucommunity/BrighterScript/blob/master/docs/readme.md)
 
@@ -59,12 +63,39 @@ BrighterScript adds several new features to the BrightScript language such as Na
   - And if it's not enough, the [plugin API](https://github.com/rokucommunity/brighterscript/blob/master/docs/plugins.md) allows extending the compiler to provide extra diagnostics or transformations.
 
 ## Who uses Brighterscript?
-
-Brighterscript is used by [applicaster](https://www.applicaster.com/), [The miracle channel](https://miraclechannel.ca/corco/), and in open source projects such as [rooibos](https://github.com/georgejecook/rooibos/blob/master/docs/index.md), and the [maestro framework](https://github.com/georgejecook/maestro/blob/master/docs/index.md). The language has been in use for almost a year, and there are at least 2,000+ BrighterScript transpiled files on published channels.
-
-The BrighterScript project is used to power the popular [Brightscript Language](https://marketplace.visualstudio.com/items?itemName=celsoaf.brightscript) VSCode extension, and other tools.
-
-More projects are adopting BrighterScript all the time, from using the new BrighterScript language features to simply using the compiler as part of their build pipeline. Be sure to watch this space!
+<br/>
+<p align="center">
+    <a href="https://www.fubo.tv/">
+      <img height="38" src="https://user-images.githubusercontent.com/2544493/192530108-eb470b85-e687-4575-af69-254aab13428c.png">
+    </a>&nbsp;&nbsp;&nbsp;
+    <a href="mailto:chris@inverted-solutions.com">
+      <img height="38" src="https://user-images.githubusercontent.com/2544493/197794500-2bac4903-ed00-463a-b243-24c68fba7962.png">
+    </a>&nbsp;&nbsp;&nbsp;
+    <a href="https://www.applicaster.com/">
+      <img height="38" src="https://user-images.githubusercontent.com/2544493/192591901-20441fc8-3c6c-45ea-8851-b22430e6fb8e.png">
+    </a>&nbsp;&nbsp;&nbsp;
+    <a href="https://www.redspace.com/">
+      <img height="38" src="https://user-images.githubusercontent.com/2544493/195908446-8d9652f8-9877-426f-b3c6-09119d788fd8.png">
+    </a>&nbsp;&nbsp;&nbsp;
+    <br/><br/>
+      <a href="https://tantawowa.com/">
+        <img height="38" src="https://user-images.githubusercontent.com/2544493/197795138-2ec870db-71fe-49e3-a014-692a3f31e6aa.png">
+      </a>&nbsp;&nbsp;&nbsp;
+     <a href="https://www.miraclechannel.ca/corcoplus">
+      <img height="38" src="https://user-images.githubusercontent.com/2544493/192593254-f2a32cd4-0482-40de-830d-c1d09690c46b.png">
+    </a>&nbsp;&nbsp;&nbsp;
+    <a href="https://channelstore.roku.com/details/222212/phototv">
+      <img height="38" src="https://user-images.githubusercontent.com/2544493/169118062-81d94da5-2323-4e31-b19d-7db3f9c88dff.png">
+    </a>&nbsp;&nbsp;&nbsp;
+    <a href="https://www.haystack.tv/">
+      <img height="38" src="https://user-images.githubusercontent.com/2544493/192610056-d1b5a382-edf4-47b9-a6a5-d2d3ee9094cb.png">
+    </a>&nbsp;&nbsp;&nbsp;
+</p>
+<br/>
+
+The BrighterScript project is used to power the popular [Brightscript Language](https://marketplace.visualstudio.com/items?itemName=rokucommunity.brightscript) VSCode extension, the [maestro framework](https://github.com/georgejecook/maestro-roku), and more.
+
+[Contact us](https://github.com/rokucommunity/brighterscript/issues/new) if you use BrighterScript in your project and would like your logo listed above. More projects are adopting BrighterScript all the time, from using the new BrighterScript language features to simply using the compiler in their build pipeline.
 
 ## What's with the name?
 The name BrighterScript is a compliment to everything that is great about Roku's awesome BrightScript language. Naming things is hard, and discoverability and recognizability are both very important. Here are the reasons we chose this name:
@@ -133,128 +164,27 @@ If you need to configure `bsc`, you can do so in two ways:
 ## bsconfig.json
 
 ### Overview
-The presence of a `bsconfig.json` file in a directory indicates that the directory is the root of a BrightScript project. The `bsconfig.json` file specifies the root files and the compiler options required to compile the project.
-
-### Configuration inheritance with `extends`
-
-A `bsconfig.json` file can inherit configurations from another file using the `extends` property.
-
-The extends is a top-level property in `bsconfig.json`. `extends`’ value is a string containing a path to another configuration file to inherit from.
-
-The configuration from the base file are loaded first, then overridden by those in the inheriting config file. If a circularity is encountered, we report an error.
-
-The `files` property from the inheriting config file overwrite those from the base config file.
-
-All relative paths found in the configuration file will be resolved relative to the configuration file they originated in.
-
-### Optional `extends` and `project`
-There are situations where you want to store some compiler settings in a config file, but not fail if that config file doesn't exist. To do this, you can denote that your `extends` or `project` path is optional by prefixing it with a question mark (`?`). For example:
-
- - **bsconfig.json** `extends`
-    ```json
-    {
-      "extends": "?path/to/optional/bsconfig.json"
-    }
-    ```
- - CLI "extends"
-    ```
-    bsc --extends "?path/to/optional/bsconfig.json"
-    ```
-
- - CLI `project` argument
-    ```
-    bsc --project "?path/to/optional/bsconfig.json"
-    ```
- - Node.js API `extends`
-    ```
-    var programBuilder = new ProgramBuilder({
-        "extends": "?path/to/optional/bsconfig.json"
-    });
-    ```
- - Node.js API `project`
-    ```
-    var programBuilder = new ProgramBuilder({
-        "project": "?path/to/optional/bsconfig.json"
-    });
-    ```
-
-### bsconfig.json options
-
-These are the options available in the `bsconfig.json` file.
-
- - **project**: `string` - A path to a project file. This is really only passed in from the command line or the NodeJS API, and should not be present in `bsconfig.json` files. Prefix with a question mark (?) to prevent throwing an exception when the file does not exist.
-
- - **extends**: `string` - Relative or absolute path to another `bsconfig.json` file that this `bsconfig.json` file should import and then override. Prefix with a question mark (?) to prevent throwing an exception when the file does not exist.
-
- - **cwd**: `string` - Override the current working directory
-
- - **rootDir**: `string` - The root directory of your roku project. Defaults to current directory
-
- - **files**: ` (string | string[] | { src: string | string[]; dest?: string })[]` - The list file globs used to find all files for the project. If using the {src;dest;} format, you can specify a different destination directory for the matched files in src.
-
- - **outFile**: `string` -  The path (including filename) where the output file should be placed (defaults to `"./out/[WORKSPACE_FOLDER_NAME].zip"`).
-
- - **createPackage**: `boolean` - Creates a zip package. Defaults to true. This setting is ignored when `deploy` is enabled.
-
- - **watch**: `boolean` -  If true, the server will keep running and will watch and recompile on every file change.
-
- - **deploy**: `boolean` -  If true, after a successful build, the project will be deployed to the Roku specified in host.
-
- - **host**: `string` -  The host of the Roku that this project will deploy to.
-
- - **username**: `string` - the username to use when deploying to a Roku device.
-
- - **password**: `string` - The password to use when deploying to a roku device.
-
- - **emitFullPaths**: `boolean` -  Emit full paths to files when printing diagnostics to the console. Defaults to false
-
- - **diagnosticFilters**: `Array<string | number | {src: string; codes: number[]}` - A list of filters used to hide diagnostics.
-   - A `string` value should be a relative-to-root-dir or absolute file path or glob pattern of the files that should be excluded. Any file matching this pattern will have all diagnostics supressed.
-   - A `number` value should be a diagnostic code. This will supress all diagnostics with that code for the whole project.
-   - An object can also be provided to filter specific diagnostic codes for a file pattern. For example,
-        ```jsonc
-        "diagnosticFilters": [{
-            "src": "vendor/**/*",
-            "codes": [1000, 1011] //ignore these specific codes from vendor libraries
-        }]
-        ```
- - **diagnosticLevel**: `'hint' | 'info' | 'warn' | 'error'` - Specify what diagnostic levels are printed to the console. This has no effect on what diagnostics are reported in the LanguageServer. Defaults to 'warn'
-
- - **autoImportComponentScript**: `bool` - BrighterScript only: will automatically import a script at transpile-time for a component with the same name if it exists.
-
- - **sourceRoot**: `string` - Override the root directory path where debugger should locate the source files. The location will be embedded in the source map to help debuggers locate the original source files. This only applies to files found within rootDir. This is useful when you want to preprocess files before passing them to BrighterScript, and want a debugger to open the original files. This option also affects the `SOURCE_FILE_PATH` and `SOURCE_LOCATION` source literals.
-
- - **plugins**: `Array<string>` - List of node scripts or npm modules to load as plugins to the BrighterScript compiler.
-
-## Ignore errors and warnings on a per-line basis
-In addition to disabling an entire class of errors in `bsconfig.json` by using `ignoreErrorCodes`, you may also disable errors for a subset of the complier rules within a file with the following comment flags:
- - `bs:disable-next-line`
- - `bs:disable-next-line: code1 code2 code3`
- - `bs:disable-line`
- - `bs:disable-line: code1 code2 code3`
-
-Here are some examples:
-
-```BrightScript
-sub Main()
-    'disable errors about invalid syntax here
-    'bs:disable-next-line
-    DoSomething(
-
-    DoSomething( 'bs:disable-line
-
-    'disable errors about wrong parameter count
-    DoSomething(1,2,3) 'bs:disable-next-line
-
-    DoSomething(1,2,3) 'bs:disable-next-line:1002
-end sub
-
-sub DoSomething()
-end sub
+The presence of a `bsconfig.json` file in a directory indicates that the directory is the root of a BrightScript project. The `bsconfig.json` file specifies the root files and the compiler options required to compile the project. Here is a minimal example, which is recommended for new projects:
+
+```jsonc
+{
+    "rootDir": "src",
+    "files": [
+        "**/*"
+    ],
+    "stagingFolderPath": "dist",
+    "retainStagingFolder": true,
+    //this flag tells BrighterScript that for every xml file, try to import a .bs file with the same name and location
+    "autoImportComponentScript": true,
+    "sourceMap": true
+}
 ```
 
-The primary motivation for this feature was to provide a stopgap measure to hide incorrectly-thrown errors on legitimate BrightScript code due to parser bugs. This is still a new project and it is likely to be missing support for certain BrightScript syntaxes. It is recommended that you only use these comments when absolutely necessary.
+More information on the config file format may be found in the [bsconfig.json documentation](https://github.com/rokucommunity/BrighterScript/blob/master/docs/bsconfig.md).
+
+## Suppressing compiler messages
 
+The BrighterScript compiler emits errors and warnings when it encounters potentially invalid code. Errors and warnings may also be emitted by compiler plugins, such as by [the BrighterScript linter](https://github.com/rokucommunity/bslint). These messages can be suppressed if needed; see [the documentation](https://github.com/rokucommunity/BrighterScript/blob/master/docs/suppressing-compiler-messages.md).
 
 ## ropm support
 In order for BrighterScript-transpiled projects to work as ropm modules, they need a reference to [bslib](https://github.com/rokucommunity/bslib/blob/master/source/bslib.brs) (the BrightScript runtime library for BrighterScript features) in their package. As `ropm` and `brighterscript` become more popular, this could result in many duplicate copies of `bslib.brs`.

package/bsconfig.schema.json

@@ -21,6 +21,21 @@
             "description": "The root directory of your Roku project. Defaults to the current working directory (or cwd property)",
             "type": "string"
         },
+        "manifest": {
+            "description": "A entry to modify manifest values",
+            "type": "object",
+            "properties": {
+                "bs_const": {
+                    "description": "A dictionary of bs_consts to change or add to the manifest. Each entry ",
+                    "type": "object",
+                    "patternProperties": {
+                        "^.+$": {
+                            "type": ["boolean", "null"]
+                        }
+                    }
+                }
+            }
+        },
         "files": {
             "description": "The list of files that should be used in this project. Supports globs. Optionally, you can specify an object with `src` and `dest` properties to move files from one location into a different destination location",
             "default": [
@@ -105,13 +120,24 @@
             "description": " The password to use when deploying to a Roku device",
             "type": "string"
         },
+        "retainStagingDir": {
+            "type": "boolean",
+            "description": "Prevent the staging folder from being deleted after the deployment package is created.  This is helpful for troubleshooting why your package isn't being created the way you expected.",
+            "default": false
+        },
         "retainStagingFolder": {
             "type": "boolean",
+            "deprecated": true,
             "description": "Prevent the staging folder from being deleted after the deployment package is created.  This is helpful for troubleshooting why your package isn't being created the way you expected.",
             "default": false
         },
+        "stagingDir": {
+            "type": "string",
+            "description": "The path to the staging folder (where all files are copied before creating the zip package)"
+        },
         "stagingFolderPath": {
             "type": "string",
+            "deprecated": true,
             "description": "The path to the staging folder (where all files are copied before creating the zip package)"
         },
         "ignoreErrorCodes": {
@@ -128,6 +154,16 @@
                 ]
             }
         },
+        "diagnosticSeverityOverrides": {
+            "description": "A map of error codes with their severity level override (error|warn|info)",
+            "type": "object",
+            "patternProperties": {
+                ".{1,}": {
+                    "type": ["number", "string"],
+                    "enum": ["error", "warn", "info", "hint"]
+                }
+            }
+        },
         "emitFullPaths": {
             "description": "Emit full paths to files when printing diagnostics to the console.",
             "type": "boolean",
@@ -138,6 +174,11 @@
             "type": "boolean",
             "default": false
         },
+        "removeParameterTypes": {
+            "description": "Removes the explicit type to function's parameters and return (i.e. the `as type` syntax) ",
+            "type": "boolean",
+            "default": false
+        },
         "diagnosticFilters": {
             "description": "A collection of filters used to hide diagnostics for certain files",
             "type": "array",
@@ -165,7 +206,10 @@
                                 "items": {
                                     "anyOf": [
                                         {
-                                            "type": ["number", "string"],
+                                            "type": [
+                                                "number",
+                                                "string"
+                                            ],
                                             "description": "A code of diagnostics that should be filtered out from the files matched in 'src'"
                                         }
                                     ]
@@ -188,6 +232,18 @@
                 ]
             }
         },
+        "require": {
+            "description": "A list of scripts or modules to pass to node's `require()` on startup. This is useful for doing things like ts-node registration",
+            "type": "array",
+            "items": {
+                "anyOf": [
+                    {
+                        "type": "string",
+                        "description": "a path to a node script or an npm module to load dynamically at startup."
+                    }
+                ]
+            }
+        },
         "autoImportComponentScript": {
             "description": "When enabled, every xml component will search for a .bs or .brs file with the same name in the same folder, and add it as a script import if found. Disabled by default",
             "type": "boolean",
@@ -220,6 +276,16 @@
                 "warn",
                 "error"
             ]
+        },
+        "allowBrighterScriptInBrightScript": {
+            "description": "Allow brighterscript features (classes, interfaces, etc...) to be included in BrightScript (`.brs`) files, and force those files to be transpiled.",
+            "type": "boolean",
+            "default": false
+        },
+        "legacyCallfuncHandling": {
+            "description": "Legacy RokuOS versions required at least one argument in callfunc() invocations. Previous brighterscript versions handled this by inserting invalid as an argument when no other args are present. This is not necessary in modern RokuOS versions.",
+            "type": "boolean",
+            "default": false
         }
     }
-}
+}

package/dist/ActionPipeline.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Enforces that a single action can be running at a time
+ */
+export declare class ActionPipeline {
+    private workQueue;
+    run<T extends Action<any>, R extends Awaited<PromiseLike<ReturnType<T>>>>(action: T): Promise<R>;
+    private process;
+    private isProcessing;
+}
+export declare type Action<T> = () => T | PromiseLike<T>;

package/dist/ActionPipeline.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ActionPipeline = void 0;
+const deferred_1 = require("./deferred");
+/**
+ * Enforces that a single action can be running at a time
+ */
+class ActionPipeline {
+    constructor() {
+        this.workQueue = [];
+        this.isProcessing = false;
+    }
+    run(action) {
+        const work = {
+            action: action,
+            deferred: new deferred_1.Deferred()
+        };
+        this.workQueue.push(work);
+        this.process();
+        return work.deferred.promise;
+    }
+    process() {
+        //if we're already processing,
+        if (this.isProcessing) {
+            return;
+        }
+        while (this.workQueue.length > 0) {
+            const work = this.workQueue.shift();
+            try {
+                const result = Promise.resolve(work.action());
+                work.deferred.resolve(result);
+            }
+            catch (e) {
+                work.deferred.reject(e);
+            }
+        }
+    }
+}
+exports.ActionPipeline = ActionPipeline;
+//# sourceMappingURL=ActionPipeline.js.map

package/dist/ActionPipeline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ActionPipeline.js","sourceRoot":"","sources":["../src/ActionPipeline.ts"],"names":[],"mappings":";;;AAAA,yCAAsC;AAEtC;;GAEG;AACH,MAAa,cAAc;IAA3B;QACY,cAAS,GAAqB,EAAE,CAAC;QA6BjC,iBAAY,GAAG,KAAK,CAAC;IACjC,CAAC;IA5BU,GAAG,CAAuE,MAAS;QACtF,MAAM,IAAI,GAAG;YACT,MAAM,EAAE,MAAM;YACd,QAAQ,EAAE,IAAI,mBAAQ,EAAO;SAChC,CAAC;QACF,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC1B,IAAI,CAAC,OAAO,EAAE,CAAC;QACf,OAAO,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC;IACjC,CAAC;IAEO,OAAO;QACX,8BAA8B;QAC9B,IAAI,IAAI,CAAC,YAAY,EAAE;YACnB,OAAO;SACV;QACD,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE;YAC9B,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;YACpC,IAAI;gBACA,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAC1B,IAAI,CAAC,MAAM,EAAE,CAChB,CAAC;gBACF,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;aACjC;YAAC,OAAO,CAAC,EAAE;gBACR,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;aAC3B;SACJ;IACL,CAAC;CAEJ;AA/BD,wCA+BC"}

package/dist/AstValidationSegmenter.d.ts

@@ -0,0 +1,42 @@
+import type { DottedGetExpression, TypeExpression, VariableExpression } from './parser/Expression';
+import type { TypeChainEntry } from './interfaces';
+import type { AstNode } from './parser/AstNode';
+import { SymbolTypeFlag } from './SymbolTypeFlag';
+import type { Token } from './lexer/Token';
+import type { BrsFile } from './files/BrsFile';
+export declare const InsideSegmentWalkMode: number;
+export interface UnresolvedSymbol {
+    typeChain: TypeChainEntry[];
+    flags: SymbolTypeFlag;
+    endChainFlags: SymbolTypeFlag;
+    containingNamespaces: string[];
+    file: BrsFile;
+    lookups: string[];
+}
+export interface AssignedSymbol {
+    token: Token;
+    node: AstNode;
+}
+export declare class AstValidationSegmenter {
+    file: BrsFile;
+    validatedSegments: Map<AstNode, boolean>;
+    segmentsForValidation: AstNode[];
+    singleValidationSegments: Set<AstNode>;
+    unresolvedSegmentsSymbols: Map<AstNode, Set<UnresolvedSymbol>>;
+    assignedTokensInSegment: Map<AstNode, Set<AssignedSymbol>>;
+    ast: AstNode;
+    constructor(file: BrsFile);
+    reset(): void;
+    processTree(ast: AstNode): void;
+    checkExpressionForUnresolved(segment: AstNode, expression: VariableExpression | DottedGetExpression | TypeExpression, assignedSymbolsNames?: Set<string>): any;
+    private currentNamespaceStatement;
+    private currentClassStatement;
+    checkSegmentWalk(segment: AstNode): void;
+    getAllUnvalidatedSegments(): AstNode[];
+    getSegmentsWithChangedSymbols(changedSymbols: Map<SymbolTypeFlag, Set<string>>): AstNode[];
+    markSegmentAsValidated(segment: AstNode): void;
+    unValidateAllSegments(): void;
+    hasUnvalidatedSegments(): boolean;
+    checkIfSegmentNeedsRevalidation(segment: AstNode, changedSymbols: Map<SymbolTypeFlag, Set<string>>): boolean;
+    markSegmentsInvalidatedBySymbol(symbolName: string, flag: SymbolTypeFlag): void;
+}