Add utilities to produce diagnostics

lib/diagnostics.js

@@ -0,0 +1,44 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addDiagnostic = exports.makeDiagnostic = void 0;
+const fs_1 = require("fs");
+const path_1 = __importDefault(require("path"));
+const logging_1 = require("./logging");
+/**
+ * Constructs a new diagnostic message with the specified id and name, as well as optional additional data.
+ *
+ * @param id An identifier under which it makes sense to group this diagnostic message.
+ * @param name Display name for the ID.
+ * @param data Optional additional data to initialize the diagnostic with.
+ * @returns Returns the new diagnostic message.
+ */
+function makeDiagnostic(id, name, data = undefined) {
+    return {
+        ...data,
+        timestamp: data?.timestamp ?? new Date().toISOString(),
+        source: { ...data?.source, id, name },
+    };
+}
+exports.makeDiagnostic = makeDiagnostic;
+/**
+ * Writes the given diagnostic to the database.
+ *
+ * @param config The configuration that tells us where to store the diagnostic.
+ * @param diagnostic The diagnostic message to add to the database.
+ */
+function addDiagnostic(config, diagnostic) {
+    const logger = (0, logging_1.getActionsLogger)();
+    const diagnosticsPath = path_1.default.resolve(config.dbLocation, "diagnostic");
+    const jsonPath = path_1.default.resolve(diagnosticsPath, `codeql-action-${diagnostic.timestamp}.json`);
+    try {
+        (0, fs_1.writeFileSync)(jsonPath, JSON.stringify(diagnostic));
+    }
+    catch (err) {
+        logger.warning(`Unable to write diagnostic message to database: ${err}`);
+    }
+}
+exports.addDiagnostic = addDiagnostic;
+//# sourceMappingURL=diagnostics.js.map

lib/diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.js","sourceRoot":"","sources":["../src/diagnostics.ts"],"names":[],"mappings":";;;;;;AAAA,2BAAmC;AACnC,gDAAwB;AAGxB,uCAA6C;AAmD7C;;;;;;;GAOG;AACH,SAAgB,cAAc,CAC5B,EAAU,EACV,IAAY,EACZ,OAA+C,SAAS;IAExD,OAAO;QACL,GAAG,IAAI;QACP,SAAS,EAAE,IAAI,EAAE,SAAS,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACtD,MAAM,EAAE,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,IAAI,EAAE;KACtC,CAAC;AACJ,CAAC;AAVD,wCAUC;AAED;;;;;GAKG;AACH,SAAgB,aAAa,CAAC,MAAc,EAAE,UAA6B;IACzE,MAAM,MAAM,GAAG,IAAA,0BAAgB,GAAE,CAAC;IAClC,MAAM,eAAe,GAAG,cAAI,CAAC,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC;IACtE,MAAM,QAAQ,GAAG,cAAI,CAAC,OAAO,CAC3B,eAAe,EACf,iBAAiB,UAAU,CAAC,SAAS,OAAO,CAC7C,CAAC;IAEF,IAAI;QACF,IAAA,kBAAa,EAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC;KACrD;IAAC,OAAO,GAAG,EAAE;QACZ,MAAM,CAAC,OAAO,CAAC,mDAAmD,GAAG,EAAE,CAAC,CAAC;KAC1E;AACH,CAAC;AAbD,sCAaC"}

src/diagnostics.ts

@@ -0,0 +1,95 @@
+import { writeFileSync } from "fs";
+import path from "path";
+
+import { Config } from "./config-utils";
+import { getActionsLogger } from "./logging";
+
+/** 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;
+  };
+  /** 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. */
+  plaintextMessage?: string;
+  /** List of help links intended to supplement the `plaintextMessage`. */
+  helpLinks?: string[];
+  /** SARIF severity */
+  severity?: "error" | "warning" | "note";
+  visibility?: {
+    /** True if the message should be displayed on the status page (defaults to false) */
+    statusPage?: boolean;
+    /**
+     * True if the message should be counted in the diagnostics summary table printed by `codeql database analyze`
+     * (defaults to false)
+     */
+    cliSummaryTable?: boolean;
+    /** True if the message should be sent to telemetry (defaults to false) */
+    telemetry?: boolean;
+  };
+  location?: {
+    /** Path to the affected file if appropriate, relative to the source root */
+    file?: string;
+    startLine?: number;
+    startColumn?: number;
+    endLine?: number;
+    endColumn?: number;
+  };
+  /** Structured metadata about the diagnostic message */
+  attributes?: { [key: string]: any };
+}
+
+/**
+ * Constructs a new diagnostic message with the specified id and name, as well as optional additional data.
+ *
+ * @param id An identifier under which it makes sense to group this diagnostic message.
+ * @param name Display name for the ID.
+ * @param data Optional additional data to initialize the diagnostic with.
+ * @returns Returns the new diagnostic message.
+ */
+export function makeDiagnostic(
+  id: string,
+  name: string,
+  data: Partial<DiagnosticMessage> | undefined = undefined,
+): DiagnosticMessage {
+  return {
+    ...data,
+    timestamp: data?.timestamp ?? new Date().toISOString(),
+    source: { ...data?.source, id, name },
+  };
+}
+
+/**
+ * Writes the given diagnostic to the database.
+ *
+ * @param config The configuration that tells us where to store the diagnostic.
+ * @param diagnostic The diagnostic message to add to the database.
+ */
+export function addDiagnostic(config: Config, diagnostic: DiagnosticMessage) {
+  const logger = getActionsLogger();
+  const diagnosticsPath = path.resolve(config.dbLocation, "diagnostic");
+  const jsonPath = path.resolve(
+    diagnosticsPath,
+    `codeql-action-${diagnostic.timestamp}.json`,
+  );
+
+  try {
+    writeFileSync(jsonPath, JSON.stringify(diagnostic));
+  } catch (err) {
+    logger.warning(`Unable to write diagnostic message to database: ${err}`);
+  }
+}