Refine Diagnostic Filters and adds human-readable diagnostic names

docs/bsconfig.md

@@ -46,7 +46,7 @@ BrighterScript only: will automatically import a script at transpile-time for a
 
 Type: `string`
 
-Override the destination directory for the bslib.brs file.  Use this if you want to customize where the bslib.brs file is located in the staging directory.  Note that using a location outside of `source` will break scripts inside `source` that depend on bslib.brs.
+Override the destination directory for the bslib.brs file. Use this if you want to customize where the bslib.brs file is located in the staging directory. Note that using a location outside of `source` will break scripts inside `source` that depend on bslib.brs.
 
 Defaults to `source`.
 
@@ -70,43 +70,69 @@ If `true`, after a successful build, the project will be deployed to the Roku sp
 
 ## `diagnosticFilters`
 
-Type: `Array<string | number | {src: string; codes: number[]}`
+Type: `Array<string | number | {files: string | Array<string | {src: string} | {dest: string}>; codes?: Array<number | string>}`
 
 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. These file paths refer to the location of the source files pre-compilation and are relative to [`rootDir`](#rootdir). Absolute file paths may be used as well.
-    - A file glob may be prefixed with `!` to make it a negative pattern which "un-ignores" the files it matches. (See examples below).
-- 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,
+- A `string` value should be a diagnostic code. This will supress all diagnostics with that code for the whole project. For example:
 
-    ```jsonc
-    "diagnosticFilters": [{
-        "src": "vendor/**/*",
-        "codes": [1000, 1011] //ignore these specific codes from vendor libraries
-    }]
-    ```
+  ```jsonc
+  "diagnosticFilters": [
+      "cannot-find-name",
+      "local-var-function-shadow",
+      "mismatch-argument-count"
+  ]
+  ```
+
+- An object can also be provided to filter specific diagnostic codes for a file pattern. If no `files` property is included, any diagnostic that matches the values in the `codes` will b e suppressed. If a `string` if given for the `files` property, it is treated as a relative-to-root-dir or absolute file path or glob pattern of the files that should be excluded. These file paths refer to the location of the source files pre-compilation and are relative to [`rootDir`](#rootdir). Absolute file paths may be used as well. For example,
+
+  ```jsonc
+  "diagnosticFilters": [{
+      "files": "vendor/**/*",
+      "codes": ["cannot-find-name", "mismatch-argument-count"] //ignore these specific codes from vendor libraries
+  }]
+  ```
+
+- If an object is provided, the `files` property could also be an array, providing either a series of globs, or a specific set of files that match _either_ their `src` or `dest` paths. For example,
+
+  ```jsonc
+  "diagnosticFilters": [{
+      "files": [
+          "vendor/**/*", // all vendor files will be suppressed
+          { "src": "themes/theme1/**/*"}, // all files coming from `themes/theme1/` will be suppressed
+          { "dest": "source/common/**/*"}, // all files from `source/common/` will be suppressed
+      ]
+      "codes": ["cannot-find-name", "mismatch-argument-count"] //ignore these specific codes
+  }]
+  ```
+
+- A file glob may be prefixed with `!` to make it a negative pattern which "un-ignores" the files it matches. (See examples below).
 
 Defaults to `undefined`.
 
 If a child bsconfig extends from a parent bsconfig, and both bsconfigs specify `diagnosticFilters`, the parent bsconfig's `diagnosticFilters` field will be completely overwritten.
 
+
+**Note:** In Brighterscript v0, all diagnostics used a numerical code. Using those legacy codes will still work, but is *deprecated*. Therefore, it is possible to use `number` values instead of string codes. Using a number (or a string representation of a number) matches all diagnostic codes that have that legacy code. For example, an entry of `1234` (or `"1234"`) would suppress any diagnostic with legacy code `1234`.
+
+
 ### Negative patterns in `diagnosticFilters`
 
 A negative pattern can be used to un-ignore some files or codes which were previously ignored. For example,
 
 ```jsonc
 "diagnosticFilters": [
-    { "src": "vendor/**/*" }, //ignore all codes from vendor libraries
-    { "src": "!vendor/unreliable/**/*" } //EXCEPT do show errors from this one specific library
+    { "files": "vendor/**/*" }, //ignore all codes from vendor libraries
+    { "files": "!vendor/unreliable/**/*" } //EXCEPT do show errors from this one specific library
 ]
 ```
 
 A specific error code can be unignored in multiple places by using a pattern which matches everything under `rootDir`. For example,
 
 ```jsonc
 "diagnosticFilters": [
-    { "src": "vendor/**/*" }, //ignore all errors from vendor libraries
-    { "src": "!*/**/*", "codes": [1000] } //EXCEPT do show this particular code everywhere
+    { "files": "vendor/**/*" }, //ignore all errors from vendor libraries
+    { "files": "!*/**/*", "codes": ["name-collision"] } //EXCEPT do show this particular code everywhere
 ]
 ```
 
@@ -126,7 +152,7 @@ A map of error codes and severity levels that will override diagnostics' severit
 
 ```jsonc
 "diagnosticSeverityOverrides": {
-    "1011": "error",   //raise a warning to an error
+    "local-var-function-shadow": "error",   //raise a warning to an error
     "LINT1001": "warn" //oops we have lots of those to fix... later
 }
 ```
@@ -156,47 +182,51 @@ Child config properties completely replace parent config properties. For example
 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`](#extends) or [`project`](#project) path is optional by prefixing it with a question mark (`?`). For example:
 
 - **bsconfig.json** `extends`
-    ```json
-    {
-      "extends": "?path/to/optional/bsconfig.json"
-    }
-    ```
+  ```json
+  {
+    "extends": "?path/to/optional/bsconfig.json"
+  }
+  ```
 - CLI "extends"
-    ```
-    bsc --extends "?path/to/optional/bsconfig.json"
-    ```
+
+  ```
+  bsc --extends "?path/to/optional/bsconfig.json"
+  ```
 
 - CLI `project` argument
-    ```
-    bsc --project "?path/to/optional/bsconfig.json"
-    ```
+  ```
+  bsc --project "?path/to/optional/bsconfig.json"
+  ```
 - Node.js API `extends`
-    ```
-    var programBuilder = new ProgramBuilder({
-        "extends": "?path/to/optional/bsconfig.json"
-    });
-    ```
+  ```
+  var programBuilder = new ProgramBuilder({
+      "extends": "?path/to/optional/bsconfig.json"
+  });
+  ```
 - Node.js API `project`
-    ```
-    var programBuilder = new ProgramBuilder({
-        "project": "?path/to/optional/bsconfig.json"
-    });
-    ```
+  ```
+  var programBuilder = new ProgramBuilder({
+      "project": "?path/to/optional/bsconfig.json"
+  });
+  ```
 
 ## `files`
 
 Type:
+
 ```typescript
 Array<
-  string |
-  string[] |
-  {
-    src: string | string[],
-    dest: string
-  }>
+  | string
+  | string[]
+  | {
+      src: string | string[];
+      dest: string;
+    }
+>;
 ```
 
 The files array is how you specify what files are included in your project. Any strings found in the files array must be relative to rootDir, and are used as include filters, meaning that if a file matches the pattern, it is included.
@@ -205,12 +235,7 @@ For most standard projects, the default files array should work just fine:
 
 ```jsonc
 {
-    "files": [
-        "source/**/*",
-        "components/**/*",
-        "images/**/*",
-        "manifest"
-    ]
+  "files": ["source/**/*", "components/**/*", "images/**/*", "manifest"]
 }
 ```
 
@@ -239,10 +264,7 @@ You can exclude files from the output by prefixing your file patterns with "!".
 
 ```jsonc
 {
-    "files": [
-        "source/**/*",
-        "!source/some/unwanted/file.brs"
-    ]
+  "files": ["source/**/*", "!source/some/unwanted/file.brs"]
 }
 ```
 
@@ -256,13 +278,13 @@ Patterns may not reference files outside of [`rootDir`](#rootdir) unless the `{
 
 ```jsonc
 {
-    "rootDir": "C:/projects/CatVideoPlayer",
-    "files": [
-        "source/main.brs",
+  "rootDir": "C:/projects/CatVideoPlayer",
+  "files": [
+    "source/main.brs",
 
-        //NOT allowed because it navigates outside the rootDir
-        "../common/promise.brs"
-    ]
+    //NOT allowed because it navigates outside the rootDir
+    "../common/promise.brs"
+  ]
 }
 ```
 
@@ -280,17 +302,17 @@ The object structure is as follows:
 
 ```typescript
 {
-    /**
-     * A glob pattern string or file path, or an array of glob pattern strings and/or file paths.
-     * These can be relative paths or absolute paths.
-     * All non-absolute paths are resolved relative to the rootDir
-     */
-    src: Array<string | string[]>;
-    /**
-     * The relative path to the location in the output folder where the files should be placed,
-     * relative to the root of the output folder
-     */
-    dest: string | undefined
+  /**
+   * A glob pattern string or file path, or an array of glob pattern strings and/or file paths.
+   * These can be relative paths or absolute paths.
+   * All non-absolute paths are resolved relative to the rootDir
+   */
+  src: Array<string | string[]>;
+  /**
+   * The relative path to the location in the output folder where the files should be placed,
+   * relative to the root of the output folder
+   */
+  dest: string | undefined;
 }
 ```
 
@@ -318,14 +340,14 @@ An example of combining regular and advanced file patterns:
 
 ```jsonc
 {
-    "rootDir": "C:/projects/CatVideoPlayer",
-    "files": [
-        "source/main.brs",
-        {
-          "src": "../common/promise.brs",
-          "dest": "source/common"
-        }
-    ]
+  "rootDir": "C:/projects/CatVideoPlayer",
+  "files": [
+    "source/main.brs",
+    {
+      "src": "../common/promise.brs",
+      "dest": "source/common"
+    }
+  ]
 }
 ```
 
@@ -337,15 +359,15 @@ For example, if you have a base project and a child project that wants to overri
 
 ```jsonc
 {
-    "files": [
-        {
-            //copy all files from the base project
-            "src": "../BaseProject/**/*"
-        },
-        // Override "../BaseProject/themes/theme.brs"
-        // with "${rootDir}/themes/theme.brs"
-        "themes/theme.brs"
-    ]
+  "files": [
+    {
+      //copy all files from the base project
+      "src": "../BaseProject/**/*"
+    },
+    // Override "../BaseProject/themes/theme.brs"
+    // with "${rootDir}/themes/theme.brs"
+    "themes/theme.brs"
+  ]
 }
 ```
 

src/BsConfig.ts

@@ -128,7 +128,7 @@ export interface BsConfig {
     /**
      * A list of filters used to exclude diagnostics from the output
      */
-    diagnosticFilters?: Array<number | string | { src: string; codes: (number | string)[] } | { src: string } | { codes: (number | string)[] }>;
+    diagnosticFilters?: Array<string | number | { files?: string | Array<string | { src: string } | { dest: string }>; codes?: Array<number | string> }>;
 
     /**
      * Specify what diagnostic types should be printed to the console. Defaults to 'warn'