From 8bc373800836cc0f74f74802315b49cbcf18f01c Mon Sep 17 00:00:00 2001 From: "Michael B. Gale" Date: Tue, 14 Jul 2026 18:49:47 +0100 Subject: [PATCH 1/5] Add `DiagnosticTag` type and `tags` property --- src/diagnostics.ts | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/src/diagnostics.ts b/src/diagnostics.ts index 65e82ce1af..e747a1e38c 100644 --- a/src/diagnostics.ts +++ b/src/diagnostics.ts @@ -6,6 +6,12 @@ import { Language } from "./languages"; import { getActionsLogger } from "./logging"; import { getCodeQLDatabasePath } from "./util"; +/** + * Known tags for diagnostics. There is currently only "internal-error", + * but others may be added in the future. + */ +export type DiagnosticTag = "internal-error"; + /** Represents a diagnostic message for the tool status page, etc. */ export interface DiagnosticMessage { /** ISO 8601 timestamp */ @@ -23,6 +29,8 @@ export interface DiagnosticMessage { * descriptor object should be nested under in SARIF. */ extractorName?: string; + /** An array of tags for the diagnostic. */ + tags?: DiagnosticTag[]; }; /** GitHub flavored Markdown formatted message. Should include inline links to any help pages. */ markdownMessage?: string; From 358d197a13c200cfd1478770b78cbae7050a4236 Mon Sep 17 00:00:00 2001 From: "Michael B. Gale" Date: Tue, 14 Jul 2026 18:57:55 +0100 Subject: [PATCH 2/5] Refactor `source` type into `DiagnosticSource` --- src/diagnostics.ts | 36 ++++++++++++++++++++---------------- 1 file changed, 20 insertions(+), 16 deletions(-) diff --git a/src/diagnostics.ts b/src/diagnostics.ts index e747a1e38c..9f90985367 100644 --- a/src/diagnostics.ts +++ b/src/diagnostics.ts @@ -12,26 +12,30 @@ import { getCodeQLDatabasePath } from "./util"; */ export type DiagnosticTag = "internal-error"; +/** Represents information about the origin of a diagnostic. */ +export interface DiagnosticSource { + /** + * An identifier under which it makes sense to group this diagnostic message. + * This is used to build the SARIF reporting descriptor object. + */ + id: string; + /** Display name for the ID. This is used to build the SARIF reporting descriptor object. */ + name: string; + /** + * Name of the CodeQL extractor. This is used to identify which tool component the reporting + * descriptor object should be nested under in SARIF. + */ + extractorName?: string; + /** An array of tags for the diagnostic. */ + tags?: DiagnosticTag[]; +} + /** Represents a diagnostic message for the tool status page, etc. */ export interface DiagnosticMessage { /** ISO 8601 timestamp */ timestamp: string; - source: { - /** - * An identifier under which it makes sense to group this diagnostic message. - * This is used to build the SARIF reporting descriptor object. - */ - id: string; - /** Display name for the ID. This is used to build the SARIF reporting descriptor object. */ - name: string; - /** - * Name of the CodeQL extractor. This is used to identify which tool component the reporting - * descriptor object should be nested under in SARIF. - */ - extractorName?: string; - /** An array of tags for the diagnostic. */ - tags?: DiagnosticTag[]; - }; + /** Information about the origin of the diagnostic. */ + source: DiagnosticSource; /** GitHub flavored Markdown formatted message. Should include inline links to any help pages. */ markdownMessage?: string; /** Plain text message. Used by components where the string processing needed to support Markdown is cumbersome. */ From 8aa21b44a3cdb669ea4faa767edd99ddc22cbd90 Mon Sep 17 00:00:00 2001 From: "Michael B. Gale" Date: Tue, 14 Jul 2026 19:06:38 +0100 Subject: [PATCH 3/5] Split `DiagnosticMessage` into `BaseDiagnosticMessage` --- src/diagnostics.ts | 47 +++++++++++++++++++++++++++++++--------------- 1 file changed, 32 insertions(+), 15 deletions(-) diff --git a/src/diagnostics.ts b/src/diagnostics.ts index 9f90985367..5b3ce19b94 100644 --- a/src/diagnostics.ts +++ b/src/diagnostics.ts @@ -12,8 +12,19 @@ import { getCodeQLDatabasePath } from "./util"; */ export type DiagnosticTag = "internal-error"; +/** Optional information about the origin of a diagnostic. */ +export type DiagnosticSourceOptions = { + /** + * Name of the CodeQL extractor. This is used to identify which tool component the reporting + * descriptor object should be nested under in SARIF. + */ + extractorName?: string; + /** An array of tags for the diagnostic. */ + tags?: DiagnosticTag[]; +}; + /** Represents information about the origin of a diagnostic. */ -export interface DiagnosticSource { +export type DiagnosticSource = { /** * An identifier under which it makes sense to group this diagnostic message. * This is used to build the SARIF reporting descriptor object. @@ -21,21 +32,19 @@ export interface DiagnosticSource { id: string; /** Display name for the ID. This is used to build the SARIF reporting descriptor object. */ name: string; - /** - * Name of the CodeQL extractor. This is used to identify which tool component the reporting - * descriptor object should be nested under in SARIF. - */ - extractorName?: string; - /** An array of tags for the diagnostic. */ - tags?: DiagnosticTag[]; -} +} & DiagnosticSourceOptions; -/** Represents a diagnostic message for the tool status page, etc. */ -export interface DiagnosticMessage { +/** + * Represents a diagnostic message for the tool status page, etc. + * + * Unlike {@link DiagnosticMessage}, properties which can automatically + * be populated are optional in this type. + */ +export type DiagnosticMessageOptions = { /** ISO 8601 timestamp */ - timestamp: string; + timestamp?: string; /** Information about the origin of the diagnostic. */ - source: DiagnosticSource; + source?: DiagnosticSourceOptions; /** GitHub flavored Markdown formatted message. Should include inline links to any help pages. */ markdownMessage?: string; /** Plain text message. Used by components where the string processing needed to support Markdown is cumbersome. */ @@ -65,7 +74,15 @@ export interface DiagnosticMessage { }; /** Structured metadata about the diagnostic message */ attributes?: { [key: string]: any }; -} +}; + +/** Represents a diagnostic message for the tool status page, etc. */ +export type DiagnosticMessage = DiagnosticMessageOptions & { + /** ISO 8601 timestamp */ + timestamp: string; + /** Information about the origin of the diagnostic. */ + source: DiagnosticSource; +}; /** Represents a diagnostic message that has not yet been written to the database. */ interface UnwrittenDiagnostic { @@ -102,7 +119,7 @@ let diagnosticCounter = 0; export function makeDiagnostic( id: string, name: string, - data: Partial | undefined = undefined, + data: DiagnosticMessageOptions | undefined = undefined, ): DiagnosticMessage { return { ...data, From f3d47397e8f733260c3939a696603d8ac9860779 Mon Sep 17 00:00:00 2001 From: "Michael B. Gale" Date: Tue, 14 Jul 2026 19:13:36 +0100 Subject: [PATCH 4/5] Add `tags` parameter to `makeTelemetryDiagnostic` --- lib/entry-points.js | 5 ++++- src/diagnostics.ts | 4 ++++ 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/lib/entry-points.js b/lib/entry-points.js index 347343d0ed..40655483f8 100644 --- a/lib/entry-points.js +++ b/lib/entry-points.js @@ -147779,13 +147779,16 @@ function flushDiagnostics(config) { unwrittenDiagnostics = []; unwrittenDefaultLanguageDiagnostics = []; } -function makeTelemetryDiagnostic(id, name, attributes) { +function makeTelemetryDiagnostic(id, name, attributes, tags) { return makeDiagnostic(id, name, { attributes, visibility: { cliSummaryTable: false, statusPage: false, telemetry: true + }, + source: { + tags } }); } diff --git a/src/diagnostics.ts b/src/diagnostics.ts index 5b3ce19b94..fa0e87c046 100644 --- a/src/diagnostics.ts +++ b/src/diagnostics.ts @@ -272,6 +272,7 @@ export function makeTelemetryDiagnostic( id: string, name: string, attributes: { [key: string]: any }, + tags?: DiagnosticTag[], ): DiagnosticMessage { return makeDiagnostic(id, name, { attributes, @@ -280,5 +281,8 @@ export function makeTelemetryDiagnostic( statusPage: false, telemetry: true, }, + source: { + tags, + }, }); } From 405f67d32613af6d6017150c523f17f0870c4a7b Mon Sep 17 00:00:00 2001 From: "Michael B. Gale" Date: Tue, 14 Jul 2026 19:22:28 +0100 Subject: [PATCH 5/5] Add `internal-error` tags to diagnostics in `mergeDefaultSetupAndUserConfigs` --- lib/entry-points.js | 6 ++++-- src/config/db-config.ts | 2 ++ 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/lib/entry-points.js b/lib/entry-points.js index 40655483f8..14c662839a 100644 --- a/lib/entry-points.js +++ b/lib/entry-points.js @@ -147990,7 +147990,8 @@ function mergeDefaultSetupAndUserConfigs(logger, fromConfigInput, fromConfigFile "Invalid Default Setup configuration keys", { invalidKeys: schemaCheckResult.invalidKeys - } + }, + ["internal-error"] ) ); } @@ -148005,7 +148006,8 @@ function mergeDefaultSetupAndUserConfigs(logger, fromConfigInput, fromConfigFile "Unrecognised Default Setup configuration keys", { unrecognisedKeys: schemaCheckResult.unknownKeys - } + }, + ["internal-error"] ) ); } diff --git a/src/config/db-config.ts b/src/config/db-config.ts index 582cfe8afc..7b5bdbd8ce 100644 --- a/src/config/db-config.ts +++ b/src/config/db-config.ts @@ -125,6 +125,7 @@ export function mergeDefaultSetupAndUserConfigs( { invalidKeys: schemaCheckResult.invalidKeys, }, + ["internal-error"], ), ); } @@ -140,6 +141,7 @@ export function mergeDefaultSetupAndUserConfigs( { unrecognisedKeys: schemaCheckResult.unknownKeys, }, + ["internal-error"], ), ); }