From 2ecdaf0cc8dba966bfc9b6d0849baee6b35045d4 Mon Sep 17 00:00:00 2001
From: Christopher Dwyer-Perkins <chris@inverted-solutions.com>
Date: Wed, 6 May 2026 10:22:32 -0300
Subject: [PATCH 1/5] Add diagnosticReporter config option for diagnostic
 output formatting

Adds a new `diagnosticReporter` setting in bsconfig.json (and a matching
`--diagnostic-reporter` CLI flag) that lets users pick how diagnostics are
rendered to the console. Accepts a single value or an array, where each
value is a preset name ("detailed", "github-actions"), a custom template
string, or an explicit object form. Multiple reporters can run in the same
build so a CI run can emit detailed terminal output and GitHub Actions PR
annotations simultaneously without a third-party tool.

Invalid reporter values are logged and skipped rather than aborting the
build; if every configured reporter is invalid the build falls back to
"detailed". Schema and docs/bsconfig.md updated.
---
 bsconfig.schema.json        |  62 +++++++++
 docs/bsconfig.md            |  52 +++++++
 src/BsConfig.ts             |  49 ++++++-
 src/ProgramBuilder.ts       |  22 ++-
 src/cli.ts                  |   8 ++
 src/diagnosticUtils.spec.ts | 269 ++++++++++++++++++++++++++++++++++++
 src/diagnosticUtils.ts      | 243 +++++++++++++++++++++++++++++++-
 7 files changed, 701 insertions(+), 4 deletions(-)

diff --git a/bsconfig.schema.json b/bsconfig.schema.json
index 7c421a0d5..520d740c4 100644
--- a/bsconfig.schema.json
+++ b/bsconfig.schema.json
@@ -8,6 +8,53 @@
             "password"
         ]
     },
+    "definitions": {
+        "diagnosticReporterValue": {
+            "oneOf": [
+                {
+                    "type": "string",
+                    "description": "Either a preset name ('detailed' or 'github-actions') or a custom template string containing at least one known placeholder."
+                },
+                {
+                    "type": "object",
+                    "required": ["type"],
+                    "properties": {
+                        "type": {
+                            "type": "string",
+                            "enum": ["detailed"]
+                        }
+                    },
+                    "additionalProperties": false
+                },
+                {
+                    "type": "object",
+                    "required": ["type"],
+                    "properties": {
+                        "type": {
+                            "type": "string",
+                            "enum": ["github-actions"]
+                        }
+                    },
+                    "additionalProperties": false
+                },
+                {
+                    "type": "object",
+                    "required": ["type", "format"],
+                    "properties": {
+                        "type": {
+                            "type": "string",
+                            "enum": ["custom"]
+                        },
+                        "format": {
+                            "type": "string",
+                            "description": "Template string. Supported placeholders: {file}, {line}, {col}, {endLine}, {endCol}, {severity}, {severityCode}, {code}, {message}, {source}."
+                        }
+                    },
+                    "additionalProperties": false
+                }
+            ]
+        }
+    },
     "properties": {
         "extends": {
             "description": "Relative or absolute path to another bsconfig.json file that this file should use as a base and then override. Prefix with a question mark (?) to prevent throwing an exception if the file does not exist.",
@@ -300,6 +347,21 @@
                 "error"
             ]
         },
+        "diagnosticReporter": {
+            "description": "Specify how diagnostics are reported to the console. Accepts a single value or an array; each diagnostic is rendered once per entry. Each value is either a preset name ('detailed', 'github-actions'), a custom template string containing at least one known placeholder ({file}, {line}, {col}, {endLine}, {endCol}, {severity}, {severityCode}, {code}, {message}, {source}), or an object with explicit `type`. Defaults to 'detailed'.",
+            "default": "detailed",
+            "oneOf": [
+                {
+                    "$ref": "#/definitions/diagnosticReporterValue"
+                },
+                {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/diagnosticReporterValue"
+                    }
+                }
+            ]
+        },
         "allowBrighterScriptInBrightScript": {
             "description": "Allow brighterscript features (classes, interfaces, etc...) to be included in BrightScript (`.brs`) files, and force those files to be transpiled.",
             "type": "boolean",
diff --git a/docs/bsconfig.md b/docs/bsconfig.md
index 13a2c12d9..25e3c59cb 100644
--- a/docs/bsconfig.md
+++ b/docs/bsconfig.md
@@ -121,6 +121,58 @@ Type: `"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"`.
 
+## `diagnosticReporter`
+
+Type: `string | { type: string; format?: string } | Array<string | { type: string; format?: string }>`
+
+Specify how diagnostics are reported to the console. Accepts a single value or an array; when given an array, each diagnostic is rendered once per entry (so you can, for example, emit detailed terminal output and GitHub Actions PR annotations from a single run). Defaults to `"detailed"`.
+
+Each value can be:
+
+- A **preset name**: `"detailed"` (the default rich, multi-line, colored output) or `"github-actions"` (one-line workflow commands like `::error file=...,line=...::message` so the GitHub Actions runner surfaces them as PR annotations).
+- A **custom template string** containing at least one of the known placeholders. The placeholders supported are:
+
+  | Placeholder      | Value |
+  |------------------|---|
+  | `{file}`         | file path (respects `emitFullPaths`) |
+  | `{line}` / `{col}` | 1-based start line / column |
+  | `{endLine}` / `{endCol}` | 1-based end line / column |
+  | `{severity}`     | `error` / `warning` / `info` / `hint` |
+  | `{severityCode}` | numeric LSP severity (1=error, 2=warning, 3=info, 4=hint) |
+  | `{code}`         | diagnostic code (e.g. `1001`) |
+  | `{message}`      | diagnostic message |
+  | `{source}`       | diagnostic source (e.g. `brs`) |
+
+  Unknown placeholders pass through unchanged so typos surface visually.
+- An **explicit object** with `type`: `{ "type": "detailed" }`, `{ "type": "github-actions" }`, or `{ "type": "custom", "format": "<template>" }`.
+
+Examples:
+
+```jsonc
+"diagnosticReporter": "detailed"
+
+"diagnosticReporter": "github-actions"
+
+// custom template
+"diagnosticReporter": "{file}:{line}:{col} {severity} BS{code}: {message}"
+
+// emit detailed terminal output AND github-actions annotations from the same run
+"diagnosticReporter": ["detailed", "github-actions"]
+
+// explicit object form (also accepts the same shapes inside an array)
+"diagnosticReporter": { "type": "custom", "format": "{file}:{line}: {message}" }
+```
+
+If a value is invalid (typo'd preset, custom template with no known placeholders, etc.) it is logged as a warning and skipped. If every configured reporter is invalid, the build falls back to `"detailed"` rather than failing.
+
+The CLI accepts the same value (single or repeated):
+
+```bash
+bsc --diagnostic-reporter detailed
+bsc --diagnostic-reporter detailed github-actions
+bsc --diagnostic-reporter '{file}:{line}: {message}'
+```
+
 ## `diagnosticSeverityOverrides`
 
 Type: `Record<string | number, 'hint' | 'info' | 'warn' | 'error'>`
diff --git a/src/BsConfig.ts b/src/BsConfig.ts
index 8cb8811b2..a31d24ed4 100644
--- a/src/BsConfig.ts
+++ b/src/BsConfig.ts
@@ -148,6 +148,29 @@ export interface BsConfig {
      */
     diagnosticLevel?: 'info' | 'hint' | 'warn' | 'error';
 
+    /**
+     * Specify how diagnostics should be reported to the console.
+     * Accepts a single value or an array. When given an array, each diagnostic is rendered
+     * once per entry (so you can, for example, get both detailed terminal output and
+     * github-actions PR annotations from a single run).
+     *
+     * Each value may be a preset name ('detailed', 'github-actions'), a custom template string
+     * (any string containing a `{` placeholder), or an object with explicit `type`.
+     *
+     * Custom templates support the following placeholders, replaced per diagnostic:
+     *   {file}, {line}, {col}, {endLine}, {endCol}, {severity}, {code}, {message}, {source}
+     *
+     * Examples:
+     *   "detailed"
+     *   "github-actions"
+     *   "{file}:{line}:{col} {severity} {code}: {message}"
+     *   { type: "custom", format: "{file}:{line}: {message}" }
+     *   ["detailed", "github-actions"]
+     *
+     * @default "detailed"
+     */
+    diagnosticReporter?: DiagnosticReporter | DiagnosticReporter[];
+
     /**
      * A list of scripts or modules to add extra diagnostics or transform the AST
      */
@@ -255,6 +278,29 @@ export interface BsConfig {
     validate?: boolean;
 }
 
+/**
+ * Discriminated union describing how diagnostics are rendered to the console.
+ * - String shorthand: a preset name ('detailed' | 'github-actions') or a template string
+ *   (any string containing a `{` is treated as a custom template).
+ * - Object form: explicit `type` so config files can stay strictly typed.
+ */
+export type DiagnosticReporter =
+    | 'detailed'
+    | 'github-actions'
+    // eslint-disable-next-line @typescript-eslint/ban-types -- string & {} preserves autocomplete for the literals above
+    | (string & {})
+    | { type: 'detailed' }
+    | { type: 'github-actions' }
+    | { type: 'custom'; format: string };
+
+/**
+ * Object form of `DiagnosticReporter` after string shorthand has been resolved.
+ */
+export type NormalizedDiagnosticReporter =
+    | { type: 'detailed' }
+    | { type: 'github-actions' }
+    | { type: 'custom'; format: string };
+
 type OptionalBsConfigFields =
     | '_ancestors'
     | 'sourceRoot'
@@ -269,7 +315,8 @@ type OptionalBsConfigFields =
     | 'diagnosticLevel'
     | 'rootDir'
     | 'stagingDir'
-    | 'minFirmwareVersion';
+    | 'minFirmwareVersion'
+    | 'diagnosticReporter';
 
 export type FinalizedBsConfig =
     Omit<Required<BsConfig>, OptionalBsConfigFields>
diff --git a/src/ProgramBuilder.ts b/src/ProgramBuilder.ts
index 81196bea4..266d947f1 100644
--- a/src/ProgramBuilder.ts
+++ b/src/ProgramBuilder.ts
@@ -327,6 +327,16 @@ export class ProgramBuilder {
         //get printing options
         const options = diagnosticUtils.getPrintDiagnosticOptions(this.options);
         const { cwd, emitFullPaths } = options;
+        //custom-template reporters are pre-resolved once so we don't recompile them per diagnostic;
+        //the resolved function is stashed on the entry as `run` so we don't have to keep a parallel array.
+        //invalid entries are warned about and skipped (we never want to abort a build over a config typo).
+        const reporters = diagnosticUtils.normalizeDiagnosticReporters(this.options?.diagnosticReporter, this.logger)
+            .map(reporter => (reporter.type === 'custom'
+                ? { ...reporter, run: diagnosticUtils.createCustomDiagnosticReporter(reporter.format) }
+                : reporter));
+        if (reporters.length === 0) {
+            return;
+        }
 
         let srcPaths = Object.keys(diagnosticsByFile).sort();
         for (let srcPath of srcPaths) {
@@ -362,8 +372,16 @@ export class ProgramBuilder {
                         message: x.message
                     };
                 });
-                //format output
-                diagnosticUtils.printDiagnostic(options, severity, filePath, lines, diagnostic, relatedInformation);
+                //format output once per configured reporter
+                for (const reporter of reporters) {
+                    if (reporter.type === 'github-actions') {
+                        diagnosticUtils.printDiagnosticGithubActions({ options: options, severity: severity, filePath: filePath, diagnostic: diagnostic });
+                    } else if (reporter.type === 'custom') {
+                        reporter.run({ options: options, severity: severity, filePath: filePath, diagnostic: diagnostic });
+                    } else {
+                        diagnosticUtils.printDiagnostic(options, severity, filePath, lines, diagnostic, relatedInformation);
+                    }
+                }
             }
         }
     }
diff --git a/src/cli.ts b/src/cli.ts
index 2a6f51430..9beb17561 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -3,6 +3,7 @@ import * as yargs from 'yargs';
 import * as path from 'path';
 import { ProgramBuilder } from './ProgramBuilder';
 import { DiagnosticSeverity } from 'vscode-languageserver';
+import { normalizeDiagnosticReporters } from './diagnosticUtils';
 import util from './util';
 import { LanguageServer } from './LanguageServer';
 import chalk from 'chalk';
@@ -24,6 +25,7 @@ let options = yargs
     .option('cwd', { type: 'string', description: 'Override the current working directory.' })
     .option('copy-to-staging', { type: 'boolean', defaultDescription: 'true', description: 'Copy project files into the staging folder, ready to be packaged.' })
     .option('diagnostic-level', { type: 'string', defaultDescription: '"warn"', description: 'Specify what diagnostic types should be printed to the console. Value can be "error", "warn", "hint", "info".' })
+    .option('diagnostic-reporter', { type: 'array', defaultDescription: '"detailed"', description: 'Specify the diagnostic reporter(s). Each value can be "detailed", "github-actions", or a template string containing placeholders like {file}, {line}, {col}, {endLine}, {endCol}, {severity}, {code}, {message}, {source}. Pass the flag multiple times (or list values after a single flag) to enable multiple reporters simultaneously.' })
     .option('plugins', { type: 'array', alias: 'plugin', description: 'A list of scripts or modules to add extra diagnostics or transform the AST.' })
     .option('deploy', { type: 'boolean', defaultDescription: 'false', description: 'Deploy to a Roku device if compilation succeeds. When in watch mode, this will deploy on every change.' })
     .option('emit-full-paths', { type: 'boolean', defaultDescription: 'false', description: 'Emit full paths to files when encountering diagnostics.' })
@@ -51,6 +53,12 @@ let options = yargs
         if (diagnosticLevel && ['error', 'warn', 'hint', 'info'].includes(diagnosticLevel) === false) {
             throw new Error(`Invalid diagnostic level "${diagnosticLevel}". Value can be "error", "warn", "hint", "info".`);
         }
+        const diagnosticReporter = argv.diagnosticReporter as string[] | undefined;
+        if (diagnosticReporter !== undefined) {
+            //surface preset typos at startup. this never throws: bad reporters are warned about
+            //via console.warn and ignored so the build still runs with whatever's left (or the default).
+            normalizeDiagnosticReporters(diagnosticReporter);
+        }
         const cwd = path.resolve(process.cwd(), argv.cwd ?? process.cwd());
         //cli-provided plugin paths should be relative to cwd
         util.resolvePathsRelativeTo(argv, 'plugins', cwd);
diff --git a/src/diagnosticUtils.spec.ts b/src/diagnosticUtils.spec.ts
index f88491da4..7a66fea13 100644
--- a/src/diagnosticUtils.spec.ts
+++ b/src/diagnosticUtils.spec.ts
@@ -21,6 +21,19 @@ describe('diagnosticUtils', () => {
         sinon.restore();
     });
 
+    function makeCtx(
+        severity: DiagnosticSeverity,
+        filePath: string | undefined,
+        diagnostic: BsDiagnostic
+    ): diagnosticUtils.DiagnosticPrintContext {
+        return {
+            options: options,
+            severity: severity,
+            filePath: filePath,
+            diagnostic: diagnostic
+        };
+    }
+
     describe('printDiagnostic', () => {
         it('does not crash when range is undefined', () => {
             //print a diagnostic that doesn't have a range...it should not explode
@@ -237,6 +250,262 @@ describe('diagnosticUtils', () => {
         });
     });
 
+    describe('normalizeDiagnosticReporters', () => {
+        function makeLogger() {
+            const warnings: string[] = [];
+            return {
+                warnings: warnings,
+                logger: { warn: (...messages: any[]) => warnings.push(messages.join(' ')) }
+            };
+        }
+
+        it('returns [detailed] when value is missing', () => {
+            expect(diagnosticUtils.normalizeDiagnosticReporters(undefined)).to.eql([{ type: 'detailed' }]);
+            expect(diagnosticUtils.normalizeDiagnosticReporters(null as any)).to.eql([{ type: 'detailed' }]);
+        });
+
+        it('resolves preset string shorthands', () => {
+            expect(diagnosticUtils.normalizeDiagnosticReporters('detailed')).to.eql([{ type: 'detailed' }]);
+            expect(diagnosticUtils.normalizeDiagnosticReporters('github-actions')).to.eql([{ type: 'github-actions' }]);
+        });
+
+        it('treats a string with at least one known placeholder as a custom template', () => {
+            expect(diagnosticUtils.normalizeDiagnosticReporters('{file}:{line}: {message}')).to.eql([{
+                type: 'custom',
+                format: '{file}:{line}: {message}'
+            }]);
+        });
+
+        it('passes through explicit object form', () => {
+            expect(diagnosticUtils.normalizeDiagnosticReporters({ type: 'detailed' })).to.eql([{ type: 'detailed' }]);
+            expect(diagnosticUtils.normalizeDiagnosticReporters({ type: 'github-actions' })).to.eql([{ type: 'github-actions' }]);
+            expect(diagnosticUtils.normalizeDiagnosticReporters({ type: 'custom', format: '{file}' })).to.eql([{
+                type: 'custom',
+                format: '{file}'
+            }]);
+        });
+
+        it('normalizes each entry of an array, in order', () => {
+            expect(diagnosticUtils.normalizeDiagnosticReporters(['detailed', 'github-actions', '{file}: {message}'])).to.eql([
+                { type: 'detailed' },
+                { type: 'github-actions' },
+                { type: 'custom', format: '{file}: {message}' }
+            ]);
+        });
+
+        it('preserves an empty array (caller has opted out of all output)', () => {
+            expect(diagnosticUtils.normalizeDiagnosticReporters([])).to.eql([]);
+        });
+
+        it('warns and skips invalid entries while keeping valid ones', () => {
+            const { logger, warnings } = makeLogger();
+            expect(diagnosticUtils.normalizeDiagnosticReporters(['detailed', 'github_actions', '{file}: {message}'], logger))
+                .to.eql([
+                    { type: 'detailed' },
+                    { type: 'custom', format: '{file}: {message}' }
+                ]);
+            expect(warnings).to.have.length(1);
+            expect(warnings[0]).to.match(/Ignoring invalid diagnostic reporter/);
+            expect(warnings[0]).to.match(/Unknown diagnostic reporter/);
+        });
+
+        it('falls back to [detailed] (and warns) when every entry is invalid', () => {
+            const { logger, warnings } = makeLogger();
+            expect(diagnosticUtils.normalizeDiagnosticReporters(['github_actions', 'frindly{'], logger))
+                .to.eql([{ type: 'detailed' }]);
+            //one warning per bad entry, plus the fallback warning
+            expect(warnings).to.have.length(3);
+            expect(warnings[0]).to.match(/Ignoring invalid diagnostic reporter/);
+            expect(warnings[1]).to.match(/Ignoring invalid diagnostic reporter/);
+            expect(warnings[2]).to.match(/falling back to "detailed"/);
+        });
+
+        it('falls back to [detailed] (and warns) when a single invalid value is given', () => {
+            const { logger, warnings } = makeLogger();
+            expect(diagnosticUtils.normalizeDiagnosticReporters('github_actions', logger))
+                .to.eql([{ type: 'detailed' }]);
+            expect(warnings).to.have.length(2);
+        });
+
+        it('warning for invalid preset includes the full supported-options list', () => {
+            const { logger, warnings } = makeLogger();
+            diagnosticUtils.normalizeDiagnosticReporters('github_actions', logger);
+            expect(warnings.join('\n')).to.match(/"detailed"/);
+            expect(warnings.join('\n')).to.match(/\{file\}/);
+        });
+
+        it('warns when a custom object is missing or has empty format', () => {
+            const { logger, warnings } = makeLogger();
+            diagnosticUtils.normalizeDiagnosticReporters([{ type: 'custom', format: '' } as any, { type: 'custom' } as any], logger);
+            expect(warnings.filter(w => w.includes('non-empty'))).to.have.length(2);
+        });
+
+        it('warns when a custom object has no known placeholders', () => {
+            const { logger, warnings } = makeLogger();
+            diagnosticUtils.normalizeDiagnosticReporters({ type: 'custom', format: 'no placeholders here' } as any, logger);
+            expect(warnings.some(w => w.includes('does not contain any known placeholders'))).to.be.true;
+        });
+
+        it('warns on unknown object type', () => {
+            const { logger, warnings } = makeLogger();
+            diagnosticUtils.normalizeDiagnosticReporters({ type: 'bogus' } as any, logger);
+            expect(warnings.some(w => w.includes('Unknown diagnostic reporter type'))).to.be.true;
+        });
+
+        it('falls back silently to console.warn when no logger is provided', () => {
+            //we just want to confirm it doesn't throw and still returns the fallback
+            const stub = sinon.stub(console, 'warn').callsFake(() => { });
+            expect(diagnosticUtils.normalizeDiagnosticReporters('totally-bogus')).to.eql([{ type: 'detailed' }]);
+            expect(stub.called).to.be.true;
+        });
+    });
+
+    describe('applyDiagnosticTemplate', () => {
+        it('substitutes known placeholders', () => {
+            expect(diagnosticUtils.applyDiagnosticTemplate('{file}:{line}:{col} {message}', {
+                file: 'src/main.bs',
+                line: '10',
+                col: '5',
+                message: 'Bad thing'
+            })).to.equal('src/main.bs:10:5 Bad thing');
+        });
+
+        it('passes unknown placeholders through unchanged so typos surface', () => {
+            expect(diagnosticUtils.applyDiagnosticTemplate('{file} {nope}', { file: 'a.bs' })).to.equal('a.bs {nope}');
+        });
+
+        it('does not match braces with non-identifier contents', () => {
+            expect(diagnosticUtils.applyDiagnosticTemplate('{} {1file} {file-path}', { file: 'a.bs' })).to.equal('{} {1file} {file-path}');
+        });
+    });
+
+    describe('printDiagnosticGithubActions', () => {
+        function capture(severity: DiagnosticSeverity, filePath: string | undefined, diagnostic: BsDiagnostic): string {
+            //restore any prior stub from a previous capture() in the same test
+            sinon.restore();
+            let captured = '';
+            sinon.stub(console, 'log').callsFake((line: string) => {
+                captured += line;
+            });
+            diagnosticUtils.printDiagnosticGithubActions(makeCtx(severity, filePath, diagnostic));
+            return captured;
+        }
+
+        it('emits the canonical workflow command for an error', () => {
+            const out = capture(DiagnosticSeverity.Error, 'src/source/main.bs', {
+                message: 'Cannot find name',
+                range: Range.create(9, 4, 9, 11),
+                code: 1001
+            } as any);
+            expect(out).to.equal('::error file=src/source/main.bs,line=10,col=5,endLine=10,endColumn=12,title=BS1001::Cannot find name');
+        });
+
+        it('maps Warning -> ::warning and Information/Hint -> ::notice', () => {
+            //info/hint are below the default 'warn' threshold, so opt them in for this test
+            options = diagnosticUtils.getPrintDiagnosticOptions({ diagnosticLevel: 'info' });
+            const range = Range.create(0, 0, 0, 1);
+            expect(capture(DiagnosticSeverity.Warning, 'a.bs', { message: 'w', range: range, code: 1 } as any))
+                .to.match(/^::warning /);
+            expect(capture(DiagnosticSeverity.Information, 'a.bs', { message: 'i', range: range, code: 1 } as any))
+                .to.match(/^::notice /);
+            expect(capture(DiagnosticSeverity.Hint, 'a.bs', { message: 'h', range: range, code: 1 } as any))
+                .to.match(/^::notice /);
+        });
+
+        it('escapes property values (commas, colons, percents) and message data (newlines)', () => {
+            const out = capture(DiagnosticSeverity.Error, 'C:\\path,with,commas\\file.bs', {
+                message: 'line one\nline two\rwith % literal',
+                range: Range.create(0, 0, 0, 1),
+                code: 99
+            } as any);
+            expect(out).to.equal(
+                '::error file=C%3A\\path%2Cwith%2Ccommas\\file.bs,line=1,col=1,endLine=1,endColumn=2,title=BS99::line one%0Aline two%0Dwith %25 literal'
+            );
+        });
+
+        it('omits file= when filePath is missing and omits title= when code is missing', () => {
+            const out = capture(DiagnosticSeverity.Error, undefined, {
+                message: 'no file no code',
+                range: Range.create(2, 3, 2, 4)
+            } as any);
+            expect(out).to.equal('::error line=3,col=4,endLine=3,endColumn=5::no file no code');
+        });
+
+        it('falls back to 1:1 when range is missing', () => {
+            const out = capture(DiagnosticSeverity.Error, 'a.bs', {
+                message: 'no range',
+                range: undefined,
+                code: 1
+            } as any);
+            expect(out).to.equal('::error file=a.bs,line=1,col=1,endLine=1,endColumn=1,title=BS1::no range');
+        });
+
+        it('respects diagnosticLevel filter', () => {
+            options = diagnosticUtils.getPrintDiagnosticOptions({ diagnosticLevel: 'error' });
+            let logged = 0;
+            sinon.stub(console, 'log').callsFake(() => {
+                logged++;
+            });
+            diagnosticUtils.printDiagnosticGithubActions(makeCtx(DiagnosticSeverity.Warning, 'a.bs', {
+                message: 'filtered',
+                range: Range.create(0, 0, 0, 1),
+                code: 1
+            } as any));
+            expect(logged).to.equal(0);
+        });
+    });
+
+    describe('createCustomDiagnosticReporter', () => {
+        function capture(template: string, severity: DiagnosticSeverity, filePath: string | undefined, diagnostic: BsDiagnostic): string {
+            //restore any prior stub from a previous capture() in the same test
+            sinon.restore();
+            let captured = '';
+            sinon.stub(console, 'log').callsFake((line: string) => {
+                captured += line;
+            });
+            diagnosticUtils.createCustomDiagnosticReporter(template)(makeCtx(severity, filePath, diagnostic));
+            return captured;
+        }
+
+        it('substitutes the standard placeholders with 1-based positions', () => {
+            const out = capture(
+                '{file}:{line}:{col}-{endLine}:{endCol} {severity} {code}: {message} ({source})',
+                DiagnosticSeverity.Warning,
+                'src/main.bs',
+                {
+                    message: 'maybe bad',
+                    range: Range.create(4, 0, 4, 6),
+                    code: 42,
+                    source: 'brs'
+                } as any
+            );
+            expect(out).to.equal('src/main.bs:5:1-5:7 warning 42: maybe bad (brs)');
+        });
+
+        it('emits empty strings for missing optional fields', () => {
+            const out = capture(
+                '[{file}][{code}][{source}] {message}',
+                DiagnosticSeverity.Error,
+                undefined,
+                { message: 'oops', range: Range.create(0, 0, 0, 1) } as any
+            );
+            expect(out).to.equal('[][][] oops');
+        });
+
+        it('respects diagnosticLevel filter', () => {
+            options = diagnosticUtils.getPrintDiagnosticOptions({ diagnosticLevel: 'error' });
+            let logged = 0;
+            sinon.stub(console, 'log').callsFake(() => {
+                logged++;
+            });
+            diagnosticUtils.createCustomDiagnosticReporter('{message}')(
+                makeCtx(DiagnosticSeverity.Warning, 'a.bs', { message: 'filtered', range: Range.create(0, 0, 0, 1), code: 1 } as any)
+            );
+            expect(logged).to.equal(0);
+        });
+    });
+
+
     describe('getDiagnosticLine', () => {
         const color = ((text: string) => text) as any;
 
diff --git a/src/diagnosticUtils.ts b/src/diagnosticUtils.ts
index 0a8835039..f69133947 100644
--- a/src/diagnosticUtils.ts
+++ b/src/diagnosticUtils.ts
@@ -1,10 +1,44 @@
 import type { Chalk } from 'chalk';
 import chalk from 'chalk';
-import type { BsConfig } from './BsConfig';
+import type { BsConfig, DiagnosticReporter, NormalizedDiagnosticReporter } from './BsConfig';
 import { DiagnosticSeverity } from 'vscode-languageserver';
 import type { BsDiagnostic } from '.';
 import type { Range } from 'vscode-languageserver';
 
+const KNOWN_DIAGNOSTIC_REPORTER_PRESETS = ['detailed', 'github-actions'] as const;
+
+/**
+ * The set of placeholder names recognized inside a custom diagnostic reporter template.
+ * `buildDiagnosticPlaceholders` is typed against this list, so adding a name here will
+ * cause a compile error until the corresponding value is supplied (and vice versa).
+ */
+export const KNOWN_DIAGNOSTIC_TEMPLATE_PLACEHOLDERS = [
+    'file',
+    'line',
+    'col',
+    'endLine',
+    'endCol',
+    'severity',
+    'severityCode',
+    'code',
+    'message',
+    'source'
+] as const;
+
+//Built directly from the known-names list so that adding a placeholder is a one-line change.
+//Names are simple identifiers (camelCase) so no regex-escaping is needed.
+const KNOWN_PLACEHOLDER_REGEX = new RegExp(`\\{(${KNOWN_DIAGNOSTIC_TEMPLATE_PLACEHOLDERS.join('|')})\\}`, 'g');
+
+function findKnownPlaceholders(template: string): string[] {
+    return template.match(KNOWN_PLACEHOLDER_REGEX) ?? [];
+}
+
+function describeDiagnosticReporterOptions(): string {
+    const presets = KNOWN_DIAGNOSTIC_REPORTER_PRESETS.map(x => `"${x}"`).join(', ');
+    const placeholders = KNOWN_DIAGNOSTIC_TEMPLATE_PLACEHOLDERS.map(x => `{${x}}`).join(', ');
+    return `Expected one of:\n  - preset name: ${presets}\n  - template containing at least one placeholder: ${placeholders}`;
+}
+
 /**
  * Prepare print diagnostic formatting options
  */
@@ -50,6 +84,82 @@ export function getPrintDiagnosticOptions(options: BsConfig) {
     };
 }
 
+/**
+ * Resolve a single `DiagnosticReporter` value into its object form.
+ * String shorthand rules:
+ *   - if the value contains at least one known `{placeholder}`, it's a custom template
+ *   - otherwise it must match one of the known preset names
+ * Throws with the full list of supported presets and placeholders when nothing matches,
+ * so typos in either bucket surface loudly.
+ */
+function normalizeOneDiagnosticReporter(value: DiagnosticReporter): NormalizedDiagnosticReporter {
+    if (typeof value === 'string') {
+        if ((KNOWN_DIAGNOSTIC_REPORTER_PRESETS as readonly string[]).includes(value)) {
+            return { type: value as 'detailed' | 'github-actions' };
+        }
+        if (findKnownPlaceholders(value).length > 0) {
+            return { type: 'custom', format: value };
+        }
+        throw new Error(
+            `Unknown diagnostic reporter "${value}". ${describeDiagnosticReporterOptions()}`
+        );
+    }
+    if (value.type === 'custom') {
+        if (typeof value.format !== 'string' || value.format.length === 0) {
+            throw new Error(`Diagnostic reporter type "custom" requires a non-empty "format" string.`);
+        }
+        if (findKnownPlaceholders(value.format).length === 0) {
+            throw new Error(
+                `Diagnostic reporter template "${value.format}" does not contain any known placeholders. Supported placeholders: ${KNOWN_DIAGNOSTIC_TEMPLATE_PLACEHOLDERS.map(x => `{${x}}`).join(', ')}`
+            );
+        }
+        return { type: 'custom', format: value.format };
+    }
+    if (value.type === 'detailed' || value.type === 'github-actions') {
+        return { type: value.type };
+    }
+    throw new Error(`Unknown diagnostic reporter type "${(value as { type: string }).type}".`);
+}
+
+/**
+ * Resolve a `DiagnosticReporter` value (or array of them) into the array of object-form
+ * reporters used by the printer.
+ *
+ * Behavior:
+ *   - missing/null value → default `[{ type: 'detailed' }]`
+ *   - explicit empty array → preserved (caller has opted out of all output)
+ *   - invalid entry inside a non-empty input → warned via `logger`, skipped
+ *   - all entries invalid → warned, falls back to `[{ type: 'detailed' }]`
+ *
+ * Bad reporters never throw — surfacing a typo shouldn't be able to abort a build.
+ */
+export function normalizeDiagnosticReporters(
+    value: DiagnosticReporter | DiagnosticReporter[] | undefined,
+    logger?: { warn(...messages: any[]): void }
+): NormalizedDiagnosticReporter[] {
+    if (value === undefined || value === null) {
+        return [{ type: 'detailed' }];
+    }
+    const inputs = Array.isArray(value) ? value : [value];
+    if (inputs.length === 0) {
+        return [];
+    }
+    const warn = (message: string) => (logger ? logger.warn(message) : console.warn(message));
+    const result: NormalizedDiagnosticReporter[] = [];
+    for (const input of inputs) {
+        try {
+            result.push(normalizeOneDiagnosticReporter(input));
+        } catch (e: any) {
+            warn(`Ignoring invalid diagnostic reporter: ${e?.message ?? String(e)}`);
+        }
+    }
+    if (result.length === 0) {
+        warn(`No valid diagnostic reporters configured; falling back to "detailed".`);
+        return [{ type: 'detailed' }];
+    }
+    return result;
+}
+
 /**
  * Format output of one diagnostic
  */
@@ -196,3 +306,134 @@ export function getDiagnosticSquigglyText(line: string | undefined, startCharact
     }
     return squiggle;
 }
+
+/**
+ * Build the placeholder values used by the custom-template reporter.
+ * The return type is keyed off `KNOWN_DIAGNOSTIC_TEMPLATE_PLACEHOLDERS`, so
+ * the compiler enforces that the two stay in sync.
+ * Positions are 1-based to match editor/CI conventions; missing ranges fall back to 1.
+ */
+function buildDiagnosticPlaceholders(
+    severity: DiagnosticSeverity,
+    severityText: string,
+    filePath: string | undefined,
+    diagnostic: BsDiagnostic
+): Record<DiagnosticPlaceholderName, string> {
+    const range = diagnostic.range;
+    const line = range ? range.start.line + 1 : 1;
+    const col = range ? range.start.character + 1 : 1;
+    const endLine = range ? range.end.line + 1 : line;
+    const endCol = range ? range.end.character + 1 : col;
+    return {
+        file: filePath ?? '',
+        line: String(line),
+        col: String(col),
+        endLine: String(endLine),
+        endCol: String(endCol),
+        severity: severityText,
+        severityCode: String(severity),
+        code: diagnostic.code === undefined ? '' : String(diagnostic.code),
+        message: diagnostic.message ?? '',
+        source: diagnostic.source ?? ''
+    };
+}
+
+/**
+ * Substitute `{name}` placeholders in `template` using the given values.
+ * Only known placeholder names are matched; anything else (typos like `{filename}`
+ * or unrelated braces in user text) passes through unchanged.
+ */
+export function applyDiagnosticTemplate(template: string, values: Record<string, string>): string {
+    return template.replace(KNOWN_PLACEHOLDER_REGEX, (_match, name: string) => values[name]);
+}
+
+/**
+ * Escape a value for use inside a GitHub Actions workflow command.
+ * The message portion (after `::`) needs `%`, `\r`, and `\n` escaped;
+ * parameter values additionally need `,` and `:` escaped.
+ * @see https://docs.github.com/en/actions/reference/workflow-commands-for-github-actions
+ */
+function escapeGithubActionsData(value: string): string {
+    return value
+        .replace(/%/g, '%25')
+        .replace(/\r/g, '%0D')
+        .replace(/\n/g, '%0A');
+}
+
+function escapeGithubActionsProperty(value: string): string {
+    return escapeGithubActionsData(value)
+        .replace(/:/g, '%3A')
+        .replace(/,/g, '%2C');
+}
+
+const GITHUB_ACTIONS_SEVERITY_COMMAND: Record<number, string> = {
+    [DiagnosticSeverity.Error]: 'error',
+    [DiagnosticSeverity.Warning]: 'warning',
+    [DiagnosticSeverity.Information]: 'notice',
+    [DiagnosticSeverity.Hint]: 'notice'
+};
+
+/**
+ * Print one diagnostic in GitHub Actions workflow command format so the
+ * runner surfaces it as a PR annotation.
+ */
+export function printDiagnosticGithubActions(ctx: DiagnosticPrintContext): void {
+    const { options, severity, filePath, diagnostic } = ctx;
+    if (!options.includeDiagnostic[severity]) {
+        return;
+    }
+    const command = GITHUB_ACTIONS_SEVERITY_COMMAND[severity] ?? 'error';
+    const range = diagnostic.range;
+    const line = range ? range.start.line + 1 : 1;
+    const col = range ? range.start.character + 1 : 1;
+    const endLine = range ? range.end.line + 1 : line;
+    const endCol = range ? range.end.character + 1 : col;
+    const codeText = diagnostic.code === undefined ? '' : `BS${diagnostic.code}`;
+
+    const params: string[] = [];
+    if (filePath) {
+        params.push(`file=${escapeGithubActionsProperty(filePath)}`);
+    }
+    params.push(`line=${line}`);
+    params.push(`col=${col}`);
+    params.push(`endLine=${endLine}`);
+    params.push(`endColumn=${endCol}`);
+    if (codeText) {
+        params.push(`title=${escapeGithubActionsProperty(codeText)}`);
+    }
+
+    const message = escapeGithubActionsData(diagnostic.message ?? '');
+    console.log(`::${command} ${params.join(',')}::${message}`);
+}
+
+/**
+ * Build a reporter that renders each diagnostic via the given user-supplied template.
+ * See `BsConfig.diagnosticReporter` for the placeholder list.
+ */
+export function createCustomDiagnosticReporter(template: string): DiagnosticReporterFn {
+    return (ctx) => {
+        const { options, severity, filePath, diagnostic } = ctx;
+        if (!options.includeDiagnostic[severity]) {
+            return;
+        }
+        const severityText = options.severityTextMap[severity] ?? '';
+        const placeholders = buildDiagnosticPlaceholders(severity, severityText, filePath, diagnostic);
+        console.log(applyDiagnosticTemplate(template, placeholders));
+    };
+}
+
+type DiagnosticPlaceholderName = typeof KNOWN_DIAGNOSTIC_TEMPLATE_PLACEHOLDERS[number];
+
+/**
+ * Context passed to the object-shaped diagnostic reporters
+ * (`printDiagnosticGithubActions`, custom-template reporters).
+ * The detailed reporter has its own positional signature for backward compatibility.
+ */
+export interface DiagnosticPrintContext {
+    options: ReturnType<typeof getPrintDiagnosticOptions>;
+    severity: DiagnosticSeverity;
+    filePath: string | undefined;
+    diagnostic: BsDiagnostic;
+}
+
+export type DiagnosticReporterFn = (ctx: DiagnosticPrintContext) => void;

From 068d8f99d57e3cd93c1746662c426c4921d40841 Mon Sep 17 00:00:00 2001
From: Christopher Dwyer-Perkins <chris@inverted-solutions.com>
Date: Wed, 6 May 2026 10:56:16 -0300
Subject: [PATCH 2/5] Dedupe diagnostic reporters by type / custom format

---
 docs/bsconfig.md            | 73 +++++++++++++++++++++----------------
 src/diagnosticUtils.spec.ts | 38 +++++++++++++++++++
 src/diagnosticUtils.ts      | 18 ++++++++-
 3 files changed, 96 insertions(+), 33 deletions(-)

diff --git a/docs/bsconfig.md b/docs/bsconfig.md
index 25e3c59cb..a377ec7c4 100644
--- a/docs/bsconfig.md
+++ b/docs/bsconfig.md
@@ -2,36 +2,47 @@
 
 While a minimal `bsconfig.json` file is sufficient for getting started, `bsc` supports a range of helpful options.
 
-- [allowBrighterScriptInBrightScript](#allowBrighterScriptInBrightScript)
-- [autoImportComponentScript](#autoImportComponentScript)
-- [bslibDestinationDir](#bslibDestinationDir)
-- [createPackage](#createPackage)
-- [cwd](#cwd)
-- [deploy](#deploy)
-- [diagnosticFilters](#diagnosticFilters)
-- [diagnosticLevel](#diagnosticLevel)
-- [diagnosticSeverityOverrides](#diagnosticSeverityOverrides)
-- [emitDefinitions](#emitDefinitions)
-- [emitFullPaths](#emitFullPaths)
-- [extends](#extends)
-- [files](#files)
-- [host](#host)
-- [minFirmwareVersion](#minFirmwareVersion)
-- [outFile](#outFile)
-- [password](#password)
-- [plugins](#plugins)
-- [project](#project)
-- [pruneEmptyCodeFiles](#pruneEmptyCodeFiles)
-- [removeParameterTypes](#removeParameterTypes)
-- [require](#require)
-- [retainStagingDir](#retainStagingDir)
-- [rootDir](#rootDir)
-- [sourceMap](#sourceMap)
-- [relativeSourceMaps](#relativeSourceMaps)
-- [sourceRoot](#sourceRoot)
-- [stagingDir](#stagingDir)
-- [username](#username)
-- [watch](#watch)
+- [bsconfig.json options](#bsconfigjson-options)
+  - [`allowBrighterScriptInBrightScript`](#allowbrighterscriptinbrightscript)
+  - [`autoImportComponentScript`](#autoimportcomponentscript)
+  - [`bslibDestinationDir`](#bslibdestinationdir)
+  - [`createPackage`](#createpackage)
+  - [`cwd`](#cwd)
+  - [`deploy`](#deploy)
+  - [`diagnosticFilters`](#diagnosticfilters)
+    - [Negative patterns in `diagnosticFilters`](#negative-patterns-in-diagnosticfilters)
+  - [`diagnosticLevel`](#diagnosticlevel)
+  - [`diagnosticReporter`](#diagnosticreporter)
+  - [`diagnosticSeverityOverrides`](#diagnosticseverityoverrides)
+  - [`emitDefinitions`](#emitdefinitions)
+  - [`emitFullPaths`](#emitfullpaths)
+  - [`extends`](#extends)
+    - [Optional `extends` and `project`](#optional-extends-and-project)
+  - [`files`](#files)
+    - [Excluding files](#excluding-files)
+    - [File pattern resolution](#file-pattern-resolution)
+    - [Specifying file destinations](#specifying-file-destinations)
+    - [File collision handling](#file-collision-handling)
+  - [`host`](#host)
+  - [`minFirmwareVersion`](#minfirmwareversion)
+    - [Line continuation in `.brs` files](#line-continuation-in-brs-files)
+  - [`outFile`](#outfile)
+  - [`password`](#password)
+  - [`plugins`](#plugins)
+  - [`project`](#project)
+  - [`pruneEmptyCodeFiles`](#pruneemptycodefiles)
+  - [`removeParameterTypes`](#removeparametertypes)
+  - [`require`](#require)
+  - [`retainStagingDir`](#retainstagingdir)
+  - [`rootDir`](#rootdir)
+  - [`sourceMap`](#sourcemap)
+  - [`relativeSourceMaps`](#relativesourcemaps)
+    - [`relativeSourceMaps: false` (default)](#relativesourcemaps-false-default)
+    - [`relativeSourceMaps: true`](#relativesourcemaps-true)
+  - [`sourceRoot`](#sourceroot)
+  - [`stagingDir`](#stagingdir)
+  - [`username`](#username)
+  - [`watch`](#watch)
 
 ## `allowBrighterScriptInBrightScript`
 
@@ -163,7 +174,7 @@ Examples:
 "diagnosticReporter": { "type": "custom", "format": "{file}:{line}: {message}" }
 ```
 
-If a value is invalid (typo'd preset, custom template with no known placeholders, etc.) it is logged as a warning and skipped. If every configured reporter is invalid, the build falls back to `"detailed"` rather than failing.
+If a value is invalid (typo'd preset, custom template with no known placeholders, etc.) it is logged as a warning and skipped. Duplicate entries are dropped with a warning message. If every configured reporter is invalid, the build falls back to `"detailed"` rather than failing.
 
 The CLI accepts the same value (single or repeated):
 
diff --git a/src/diagnosticUtils.spec.ts b/src/diagnosticUtils.spec.ts
index 7a66fea13..4f41125d4 100644
--- a/src/diagnosticUtils.spec.ts
+++ b/src/diagnosticUtils.spec.ts
@@ -352,6 +352,44 @@ describe('diagnosticUtils', () => {
             expect(warnings.some(w => w.includes('Unknown diagnostic reporter type'))).to.be.true;
         });
 
+        it('dedupes preset entries by type and warns about each duplicate', () => {
+            const { logger, warnings } = makeLogger();
+            expect(diagnosticUtils.normalizeDiagnosticReporters(['detailed', 'github-actions', 'detailed', 'github-actions'], logger))
+                .to.eql([
+                    { type: 'detailed' },
+                    { type: 'github-actions' }
+                ]);
+            expect(warnings).to.have.length(2);
+            expect(warnings[0]).to.match(/duplicate diagnostic reporter: "detailed"/);
+            expect(warnings[1]).to.match(/duplicate diagnostic reporter: "github-actions"/);
+        });
+
+        it('dedupes custom templates by their format string', () => {
+            const { logger, warnings } = makeLogger();
+            expect(diagnosticUtils.normalizeDiagnosticReporters(
+                [
+                    '{file}: {message}',
+                    { type: 'custom', format: '{file}: {message}' },
+                    { type: 'custom', format: '{file}:{line} {message}' }
+                ],
+                logger
+            )).to.eql([
+                { type: 'custom', format: '{file}: {message}' },
+                { type: 'custom', format: '{file}:{line} {message}' }
+            ]);
+            expect(warnings).to.have.length(1);
+            expect(warnings[0]).to.match(/duplicate diagnostic reporter: custom template "\{file\}: \{message\}"/);
+        });
+
+        it('does not consider custom templates with different formats as duplicates', () => {
+            const { logger, warnings } = makeLogger();
+            expect(diagnosticUtils.normalizeDiagnosticReporters(
+                ['{file}: {message}', '{file}:{line} {message}'],
+                logger
+            )).to.have.length(2);
+            expect(warnings).to.have.length(0);
+        });
+
         it('falls back silently to console.warn when no logger is provided', () => {
             //we just want to confirm it doesn't throw and still returns the fallback
             const stub = sinon.stub(console, 'warn').callsFake(() => { });
diff --git a/src/diagnosticUtils.ts b/src/diagnosticUtils.ts
index f69133947..8bf2106dc 100644
--- a/src/diagnosticUtils.ts
+++ b/src/diagnosticUtils.ts
@@ -129,9 +129,10 @@ function normalizeOneDiagnosticReporter(value: DiagnosticReporter): NormalizedDi
  *   - missing/null value → default `[{ type: 'detailed' }]`
  *   - explicit empty array → preserved (caller has opted out of all output)
  *   - invalid entry inside a non-empty input → warned via `logger`, skipped
+ *   - duplicate entry (same preset type, or same custom-template format string) → warned, skipped
  *   - all entries invalid → warned, falls back to `[{ type: 'detailed' }]`
  *
- * Bad reporters never throw — surfacing a typo shouldn't be able to abort a build.
+ * Bad reporters never throw, surfacing a typo shouldn't be able to abort a build.
  */
 export function normalizeDiagnosticReporters(
     value: DiagnosticReporter | DiagnosticReporter[] | undefined,
@@ -145,13 +146,26 @@ export function normalizeDiagnosticReporters(
         return [];
     }
     const warn = (message: string) => (logger ? logger.warn(message) : console.warn(message));
+    //presets are deduped by `type`; custom templates are deduped by their format string. running the
+    //same reporter twice would only produce duplicate output, so it's almost always a config mistake.
+    const seen = new Set<string>();
     const result: NormalizedDiagnosticReporter[] = [];
     for (const input of inputs) {
+        let reporter: NormalizedDiagnosticReporter;
         try {
-            result.push(normalizeOneDiagnosticReporter(input));
+            reporter = normalizeOneDiagnosticReporter(input);
         } catch (e: any) {
             warn(`Ignoring invalid diagnostic reporter: ${e?.message ?? String(e)}`);
+            continue;
         }
+        const key = reporter.type === 'custom' ? `custom:${reporter.format}` : reporter.type;
+        if (seen.has(key)) {
+            const description = reporter.type === 'custom' ? `custom template "${reporter.format}"` : `"${reporter.type}"`;
+            warn(`Ignoring duplicate diagnostic reporter: ${description}`);
+            continue;
+        }
+        seen.add(key);
+        result.push(reporter);
     }
     if (result.length === 0) {
         warn(`No valid diagnostic reporters configured; falling back to "detailed".`);

From 3d4e42b6a82f633b3b101434f70f53e1b64f36a1 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Thu, 7 May 2026 15:46:37 +0000
Subject: [PATCH 3/5] rename diagnosticReporters and add reporter-order tests

Agent-Logs-Url: https://github.com/rokucommunity/brighterscript/sessions/27a2c50d-7e45-4d54-a66c-e8dfeb705996

Co-authored-by: chrisdp <9591618+chrisdp@users.noreply.github.com>
---
 docs/bsconfig.md           | 14 ++++-----
 src/BsConfig.ts            |  5 ++++
 src/ProgramBuilder.spec.ts | 60 ++++++++++++++++++++++++++++++++++++++
 src/ProgramBuilder.ts      |  5 +++-
 src/cli.ts                 | 13 ++++++---
 src/diagnosticUtils.ts     |  2 +-
 6 files changed, 86 insertions(+), 13 deletions(-)

diff --git a/docs/bsconfig.md b/docs/bsconfig.md
index a377ec7c4..8a9b5e9e6 100644
--- a/docs/bsconfig.md
+++ b/docs/bsconfig.md
@@ -12,7 +12,7 @@ While a minimal `bsconfig.json` file is sufficient for getting started, `bsc` su
   - [`diagnosticFilters`](#diagnosticfilters)
     - [Negative patterns in `diagnosticFilters`](#negative-patterns-in-diagnosticfilters)
   - [`diagnosticLevel`](#diagnosticlevel)
-  - [`diagnosticReporter`](#diagnosticreporter)
+  - [`diagnosticReporters`](#diagnosticreporters)
   - [`diagnosticSeverityOverrides`](#diagnosticseverityoverrides)
   - [`emitDefinitions`](#emitdefinitions)
   - [`emitFullPaths`](#emitfullpaths)
@@ -132,7 +132,7 @@ Type: `"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"`.
 
-## `diagnosticReporter`
+## `diagnosticReporters`
 
 Type: `string | { type: string; format?: string } | Array<string | { type: string; format?: string }>`
 
@@ -160,18 +160,18 @@ Each value can be:
 Examples:
 
 ```jsonc
-"diagnosticReporter": "detailed"
+"diagnosticReporters": "detailed"
 
-"diagnosticReporter": "github-actions"
+"diagnosticReporters": "github-actions"
 
 // custom template
-"diagnosticReporter": "{file}:{line}:{col} {severity} BS{code}: {message}"
+"diagnosticReporters": "{file}:{line}:{col} {severity} BS{code}: {message}"
 
 // emit detailed terminal output AND github-actions annotations from the same run
-"diagnosticReporter": ["detailed", "github-actions"]
+"diagnosticReporters": ["detailed", "github-actions"]
 
 // explicit object form (also accepts the same shapes inside an array)
-"diagnosticReporter": { "type": "custom", "format": "{file}:{line}: {message}" }
+"diagnosticReporters": { "type": "custom", "format": "{file}:{line}: {message}" }
 ```
 
 If a value is invalid (typo'd preset, custom template with no known placeholders, etc.) it is logged as a warning and skipped. Duplicate entries are dropped with a warning message. If every configured reporter is invalid, the build falls back to `"detailed"` rather than failing.
diff --git a/src/BsConfig.ts b/src/BsConfig.ts
index a31d24ed4..48fe567d0 100644
--- a/src/BsConfig.ts
+++ b/src/BsConfig.ts
@@ -169,6 +169,10 @@ export interface BsConfig {
      *
      * @default "detailed"
      */
+    diagnosticReporters?: DiagnosticReporter | DiagnosticReporter[];
+    /**
+     * @deprecated use `diagnosticReporters`
+     */
     diagnosticReporter?: DiagnosticReporter | DiagnosticReporter[];
 
     /**
@@ -316,6 +320,7 @@ type OptionalBsConfigFields =
     | 'rootDir'
     | 'stagingDir'
     | 'minFirmwareVersion'
+    | 'diagnosticReporters'
     | 'diagnosticReporter';
 
 export type FinalizedBsConfig =
diff --git a/src/ProgramBuilder.spec.ts b/src/ProgramBuilder.spec.ts
index 82773aff3..2382481a1 100644
--- a/src/ProgramBuilder.spec.ts
+++ b/src/ProgramBuilder.spec.ts
@@ -412,6 +412,66 @@ describe('ProgramBuilder', () => {
 
             expect(printStub.called).to.be.true;
         });
+
+        it('calls reporters in bsconfig order', () => {
+            fsExtra.outputJsonSync(s`${rootDir}/bsconfig.json`, {
+                rootDir: rootDir,
+                diagnosticReporters: ['github-actions', '{file}: {message}', 'detailed']
+            } as BsConfig);
+            builder.options = util.normalizeAndResolveConfig({
+                cwd: rootDir,
+                project: s`${rootDir}/bsconfig.json`
+            });
+
+            const callOrder: string[] = [];
+            let diagnostics = createBsDiagnostic('p1', ['m1']);
+            let f1 = diagnostics[0].file as BrsFile;
+            f1.fileContents = `l1\nl2\nl3`;
+            sinon.stub(builder, 'getDiagnostics').returns(diagnostics);
+            sinon.stub(builder.program, 'getFile').returns(f1);
+            sinon.stub(diagnosticUtils, 'printDiagnosticGithubActions').callsFake(() => {
+                callOrder.push('github-actions');
+            });
+            sinon.stub(diagnosticUtils, 'createCustomDiagnosticReporter').callsFake(() => {
+                return () => {
+                    callOrder.push('custom');
+                };
+            });
+            sinon.stub(diagnosticUtils, 'printDiagnostic').callsFake(() => {
+                callOrder.push('detailed');
+            });
+
+            builder['printDiagnostics']();
+            expect(callOrder).to.eql(['github-actions', 'custom', 'detailed']);
+        });
+
+        it('calls reporters in cli option order', () => {
+            builder.options = util.normalizeAndResolveConfig({
+                rootDir: rootDir,
+                diagnosticReporters: ['detailed', 'github-actions', '{file}: {message}']
+            });
+
+            const callOrder: string[] = [];
+            let diagnostics = createBsDiagnostic('p1', ['m1']);
+            let f1 = diagnostics[0].file as BrsFile;
+            f1.fileContents = `l1\nl2\nl3`;
+            sinon.stub(builder, 'getDiagnostics').returns(diagnostics);
+            sinon.stub(builder.program, 'getFile').returns(f1);
+            sinon.stub(diagnosticUtils, 'printDiagnostic').callsFake(() => {
+                callOrder.push('detailed');
+            });
+            sinon.stub(diagnosticUtils, 'printDiagnosticGithubActions').callsFake(() => {
+                callOrder.push('github-actions');
+            });
+            sinon.stub(diagnosticUtils, 'createCustomDiagnosticReporter').callsFake(() => {
+                return () => {
+                    callOrder.push('custom');
+                };
+            });
+
+            builder['printDiagnostics']();
+            expect(callOrder).to.eql(['detailed', 'github-actions', 'custom']);
+        });
     });
 
     it('prints diagnostic, when file has no lines', () => {
diff --git a/src/ProgramBuilder.ts b/src/ProgramBuilder.ts
index 266d947f1..cff8bf4a4 100644
--- a/src/ProgramBuilder.ts
+++ b/src/ProgramBuilder.ts
@@ -330,7 +330,10 @@ export class ProgramBuilder {
         //custom-template reporters are pre-resolved once so we don't recompile them per diagnostic;
         //the resolved function is stashed on the entry as `run` so we don't have to keep a parallel array.
         //invalid entries are warned about and skipped (we never want to abort a build over a config typo).
-        const reporters = diagnosticUtils.normalizeDiagnosticReporters(this.options?.diagnosticReporter, this.logger)
+        const reporters = diagnosticUtils.normalizeDiagnosticReporters(
+            this.options?.diagnosticReporters ?? this.options?.diagnosticReporter,
+            this.logger
+        )
             .map(reporter => (reporter.type === 'custom'
                 ? { ...reporter, run: diagnosticUtils.createCustomDiagnosticReporter(reporter.format) }
                 : reporter));
diff --git a/src/cli.ts b/src/cli.ts
index 9beb17561..ede8fcdbd 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -25,7 +25,12 @@ let options = yargs
     .option('cwd', { type: 'string', description: 'Override the current working directory.' })
     .option('copy-to-staging', { type: 'boolean', defaultDescription: 'true', description: 'Copy project files into the staging folder, ready to be packaged.' })
     .option('diagnostic-level', { type: 'string', defaultDescription: '"warn"', description: 'Specify what diagnostic types should be printed to the console. Value can be "error", "warn", "hint", "info".' })
-    .option('diagnostic-reporter', { type: 'array', defaultDescription: '"detailed"', description: 'Specify the diagnostic reporter(s). Each value can be "detailed", "github-actions", or a template string containing placeholders like {file}, {line}, {col}, {endLine}, {endCol}, {severity}, {code}, {message}, {source}. Pass the flag multiple times (or list values after a single flag) to enable multiple reporters simultaneously.' })
+    .option('diagnostic-reporters', {
+        alias: ['diagnostic-reporter'],
+        type: 'array',
+        defaultDescription: '"detailed"',
+        description: 'Specify the diagnostic reporter(s). Each value can be "detailed", "github-actions", or a template string containing placeholders like {file}, {line}, {col}, {endLine}, {endCol}, {severity}, {code}, {message}, {source}. Pass the flag multiple times (or list values after a single flag) to enable multiple reporters simultaneously.'
+    })
     .option('plugins', { type: 'array', alias: 'plugin', description: 'A list of scripts or modules to add extra diagnostics or transform the AST.' })
     .option('deploy', { type: 'boolean', defaultDescription: 'false', description: 'Deploy to a Roku device if compilation succeeds. When in watch mode, this will deploy on every change.' })
     .option('emit-full-paths', { type: 'boolean', defaultDescription: 'false', description: 'Emit full paths to files when encountering diagnostics.' })
@@ -53,11 +58,11 @@ let options = yargs
         if (diagnosticLevel && ['error', 'warn', 'hint', 'info'].includes(diagnosticLevel) === false) {
             throw new Error(`Invalid diagnostic level "${diagnosticLevel}". Value can be "error", "warn", "hint", "info".`);
         }
-        const diagnosticReporter = argv.diagnosticReporter as string[] | undefined;
-        if (diagnosticReporter !== undefined) {
+        const diagnosticReporters = argv.diagnosticReporters as string[] | undefined;
+        if (diagnosticReporters !== undefined) {
             //surface preset typos at startup. this never throws: bad reporters are warned about
             //via console.warn and ignored so the build still runs with whatever's left (or the default).
-            normalizeDiagnosticReporters(diagnosticReporter);
+            normalizeDiagnosticReporters(diagnosticReporters);
         }
         const cwd = path.resolve(process.cwd(), argv.cwd ?? process.cwd());
         //cli-provided plugin paths should be relative to cwd
diff --git a/src/diagnosticUtils.ts b/src/diagnosticUtils.ts
index 8bf2106dc..c92854aa2 100644
--- a/src/diagnosticUtils.ts
+++ b/src/diagnosticUtils.ts
@@ -422,7 +422,7 @@ export function printDiagnosticGithubActions(ctx: DiagnosticPrintContext): void
 
 /**
  * Build a reporter that renders each diagnostic via the given user-supplied template.
- * See `BsConfig.diagnosticReporter` for the placeholder list.
+ * See `BsConfig.diagnosticReporters` for the placeholder list.
  */
 export function createCustomDiagnosticReporter(template: string): DiagnosticReporterFn {
     return (ctx) => {

From c188846f52ebdeff82393deb2ab7eb73af5c3ce1 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Thu, 7 May 2026 17:41:44 +0000
Subject: [PATCH 4/5] rename schema key to diagnosticReporters

Agent-Logs-Url: https://github.com/rokucommunity/brighterscript/sessions/2a3f0f76-6c2f-49a0-bfd9-df4c3f608419

Co-authored-by: chrisdp <9591618+chrisdp@users.noreply.github.com>
---
 bsconfig.schema.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/bsconfig.schema.json b/bsconfig.schema.json
index 520d740c4..d83e4e285 100644
--- a/bsconfig.schema.json
+++ b/bsconfig.schema.json
@@ -347,7 +347,7 @@
                 "error"
             ]
         },
-        "diagnosticReporter": {
+        "diagnosticReporters": {
             "description": "Specify how diagnostics are reported to the console. Accepts a single value or an array; each diagnostic is rendered once per entry. Each value is either a preset name ('detailed', 'github-actions'), a custom template string containing at least one known placeholder ({file}, {line}, {col}, {endLine}, {endCol}, {severity}, {severityCode}, {code}, {message}, {source}), or an object with explicit `type`. Defaults to 'detailed'.",
             "default": "detailed",
             "oneOf": [

From e881d84425354fffa6fc6b38af1bc9a8b8ac808a Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Thu, 7 May 2026 17:47:16 +0000
Subject: [PATCH 5/5] remove singular diagnosticReporter option support

Agent-Logs-Url: https://github.com/rokucommunity/brighterscript/sessions/22914077-73e8-4652-b22a-c74b37805fbc

Co-authored-by: chrisdp <9591618+chrisdp@users.noreply.github.com>
---
 docs/bsconfig.md      | 6 +++---
 src/BsConfig.ts       | 8 +-------
 src/ProgramBuilder.ts | 2 +-
 src/cli.ts            | 1 -
 4 files changed, 5 insertions(+), 12 deletions(-)

diff --git a/docs/bsconfig.md b/docs/bsconfig.md
index 8a9b5e9e6..9bd5a43fa 100644
--- a/docs/bsconfig.md
+++ b/docs/bsconfig.md
@@ -179,9 +179,9 @@ If a value is invalid (typo'd preset, custom template with no known placeholders
 The CLI accepts the same value (single or repeated):
 
 ```bash
-bsc --diagnostic-reporter detailed
-bsc --diagnostic-reporter detailed github-actions
-bsc --diagnostic-reporter '{file}:{line}: {message}'
+bsc --diagnostic-reporters detailed
+bsc --diagnostic-reporters detailed github-actions
+bsc --diagnostic-reporters '{file}:{line}: {message}'
 ```
 
 ## `diagnosticSeverityOverrides`
diff --git a/src/BsConfig.ts b/src/BsConfig.ts
index 48fe567d0..9f483a63f 100644
--- a/src/BsConfig.ts
+++ b/src/BsConfig.ts
@@ -170,11 +170,6 @@ export interface BsConfig {
      * @default "detailed"
      */
     diagnosticReporters?: DiagnosticReporter | DiagnosticReporter[];
-    /**
-     * @deprecated use `diagnosticReporters`
-     */
-    diagnosticReporter?: DiagnosticReporter | DiagnosticReporter[];
-
     /**
      * A list of scripts or modules to add extra diagnostics or transform the AST
      */
@@ -320,8 +315,7 @@ type OptionalBsConfigFields =
     | 'rootDir'
     | 'stagingDir'
     | 'minFirmwareVersion'
-    | 'diagnosticReporters'
-    | 'diagnosticReporter';
+    | 'diagnosticReporters';
 
 export type FinalizedBsConfig =
     Omit<Required<BsConfig>, OptionalBsConfigFields>
diff --git a/src/ProgramBuilder.ts b/src/ProgramBuilder.ts
index cff8bf4a4..f459fac08 100644
--- a/src/ProgramBuilder.ts
+++ b/src/ProgramBuilder.ts
@@ -331,7 +331,7 @@ export class ProgramBuilder {
         //the resolved function is stashed on the entry as `run` so we don't have to keep a parallel array.
         //invalid entries are warned about and skipped (we never want to abort a build over a config typo).
         const reporters = diagnosticUtils.normalizeDiagnosticReporters(
-            this.options?.diagnosticReporters ?? this.options?.diagnosticReporter,
+            this.options?.diagnosticReporters,
             this.logger
         )
             .map(reporter => (reporter.type === 'custom'
diff --git a/src/cli.ts b/src/cli.ts
index ede8fcdbd..7f207976b 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -26,7 +26,6 @@ let options = yargs
     .option('copy-to-staging', { type: 'boolean', defaultDescription: 'true', description: 'Copy project files into the staging folder, ready to be packaged.' })
     .option('diagnostic-level', { type: 'string', defaultDescription: '"warn"', description: 'Specify what diagnostic types should be printed to the console. Value can be "error", "warn", "hint", "info".' })
     .option('diagnostic-reporters', {
-        alias: ['diagnostic-reporter'],
         type: 'array',
         defaultDescription: '"detailed"',
         description: 'Specify the diagnostic reporter(s). Each value can be "detailed", "github-actions", or a template string containing placeholders like {file}, {line}, {col}, {endLine}, {endCol}, {severity}, {code}, {message}, {source}. Pass the flag multiple times (or list values after a single flag) to enable multiple reporters simultaneously.'