@intentius/chant-lexicon-grafana 0.98.0 → 0.100.0

package/src/import/model.ts

@@ -0,0 +1,117 @@
+/**
+ * The plan `chant import` hands from the parser to the generator: the
+ * declarations one dashboard becomes, with the references between them.
+ *
+ * The parser decides what each piece of dashboard JSON becomes (which
+ * class, which props, what cannot be carried) using the tables in
+ * `./mappings.ts`. The generator decides only how the plan is written:
+ * names, modules, imports, lifted consts. It knows nothing about Grafana,
+ * so live export (#2946) can build a plan from a dashboard read over the
+ * API and write it with the same generator.
+ */
+
+/** A value in a declaration's props that refers to another declaration, written as that declaration's variable. */
+export interface DeclRef {
+  readonly $decl: string;
+}
+
+export function declRef(id: string): DeclRef {
+  return { $decl: id };
+}
+
+export function isDeclRef(v: unknown): v is DeclRef {
+  return typeof v === "object" && v !== null && typeof (v as DeclRef).$decl === "string" && Object.keys(v).length === 1;
+}
+
+/**
+ * A value written as a call to a function the package exports, e.g.
+ * `customTransformation("sortBy", { ... })` for a transformation the typed
+ * form can't hold. The arguments are values like any other.
+ */
+export interface CallValue {
+  readonly $call: string;
+  readonly args: readonly unknown[];
+}
+
+export function callValue(fn: string, args: readonly unknown[]): CallValue {
+  return { $call: fn, args };
+}
+
+export function isCallValue(v: unknown): v is CallValue {
+  return typeof v === "object" && v !== null && typeof (v as CallValue).$call === "string" && Array.isArray((v as CallValue).args) && Object.keys(v).length === 2;
+}
+
+/** Where a declaration's variable name comes from: a text to camelCase, or another declaration's name plus a suffix. */
+export type NameHint = string | { readonly of: string; readonly suffix: string };
+
+/**
+ * One declaration.
+ *
+ * - `new`: `const name = new ClassName(props);`, a declarable.
+ * - `value`: `const name: type = value;`, a plain value other declarations
+ *   refer to (a `DatasourceRef`).
+ */
+export interface Declaration {
+  /** Unique in the plan, e.g. `panel:4`, `query:4:A`, `variable:job`, `datasource:prometheus:prom`, `dashboard`. */
+  readonly id: string;
+  readonly kind: "new" | "value";
+  /** For `new`: the class. A package export unless `customClass` says the import declares it. */
+  readonly className?: string;
+  /** For `new`: the id of the `CustomClass` declaring `className`, when it is not a package export. */
+  readonly customClass?: string;
+  /**
+   * For `new`: type arguments for the class, as TypeScript source. The
+   * consts lifted out of the props are typed `PropsOf<typeof Class<...>>`,
+   * so a `Datasource<"prometheus">`'s `jsonData` const is typed as
+   * Prometheus settings rather than any plugin's.
+   */
+  readonly typeArguments?: readonly string[];
+  /** For `new`: the constructor's props, in source order. */
+  readonly props?: Record<string, unknown>;
+  /** For `value`: the value, and its type annotation with the package types it names. */
+  readonly value?: unknown;
+  readonly type?: { readonly text: string; readonly imports: readonly string[] };
+  readonly name: NameHint;
+  /** The module group it is written to (see `Plan.modules`). */
+  readonly module: string;
+  /**
+   * Declarations with the same unit stay in the same file when a module is
+   * split (a panel and its queries). Defaults to the id.
+   */
+  readonly unit?: string;
+  /** Comment lines written above it. */
+  readonly comment?: readonly string[];
+}
+
+/** A panel or query class the import declares, for a plugin chant has no class for. */
+export interface CustomClass {
+  /** e.g. `panel-class:grafana-clock-panel`, `query-class:elasticsearch`. */
+  readonly id: string;
+  readonly className: string;
+  /** `definePanel` or `defineQuery`. */
+  readonly factory: "definePanel" | "defineQuery";
+  /** The definition object passed to the factory. */
+  readonly definition: Record<string, unknown>;
+  readonly comment: readonly string[];
+}
+
+/** One module group: a base file name and the doc comment at its top. */
+export interface ModuleSpec {
+  readonly key: string;
+  /** File name without `.ts`; `-1`, `-2`, ... is added when the group is split. */
+  readonly file: string;
+  readonly summary: string;
+}
+
+/** Everything one dashboard becomes. */
+export interface Plan {
+  /** The directory its modules are written to, relative to the output directory. `""` for none. */
+  readonly directory: string;
+  /** Modules in the order they are written. */
+  readonly modules: readonly ModuleSpec[];
+  /** Declarations in dependency order: a declaration only refers to ones before it. */
+  readonly declarations: readonly Declaration[];
+  readonly customClasses: readonly CustomClass[];
+  /** Declarations exported even when no other module imports them (the dashboard). */
+  readonly exports: readonly string[];
+}

package/src/import/normalize-alerting.ts

@@ -0,0 +1,101 @@
+/**
+ * An alerting provisioning file in a canonical form, so two files Grafana
+ * provisions the same way compare equal. The round-trip tests compare the
+ * source (with the importer's edits applied) and the rebuilt file through
+ * this.
+ *
+ * What it treats as equal, each from Grafana's file reader
+ * (`pkg/services/provisioning/alerting/*_types.go`, v12.4.11 and v13.2.2):
+ *
+ * - `orgId: 1` and no `orgId` (a value below 1 reads as 1);
+ * - a rule's `noDataState: NoData`, `execErrState: Alerting`, `for: 0s`,
+ *   `keepFiringFor: 0s`, `isPaused: false`, `panelId: 0`, empty `labels`
+ *   and `annotations`, and the same left out;
+ * - a query's `queryType: ""`, and a `relativeTimeRange` of 0 to 0, and
+ *   the same left out;
+ * - an expression model's `datasource` of `__expr__` and a `refId` equal
+ *   to the query's, and the same left out (Grafana sets both);
+ * - `disableResolveMessage: false` and none;
+ * - the order of rule groups, contact points, mute timings and templates,
+ *   which chant writes sorted.
+ */
+
+import { EXPRESSION_DATASOURCE_UID } from "../alerting";
+import { isObject } from "./normalize";
+
+type Json = Record<string, unknown>;
+
+function dropOrg(o: Json): Json {
+  const { orgId, ...rest } = o;
+  return orgId === undefined || orgId === 1 || (typeof orgId === "number" && orgId < 1) ? rest : o;
+}
+
+function isEmpty(v: unknown): boolean {
+  return v === undefined || v === null || (isObject(v) && Object.keys(v).length === 0);
+}
+
+function query(q: Json): Json {
+  const out: Json = { ...q };
+  if (out.queryType === "" || out.queryType === undefined) delete out.queryType;
+  const r = out.relativeTimeRange;
+  if (isObject(r) && (r.from ?? 0) === 0 && (r.to ?? 0) === 0) delete out.relativeTimeRange;
+  else if (isObject(r)) out.relativeTimeRange = { from: r.from ?? 0, to: r.to ?? 0 };
+  if (out.datasourceUid === EXPRESSION_DATASOURCE_UID && isObject(out.model)) {
+    const m: Json = { ...out.model };
+    if (isObject(m.datasource) && m.datasource.uid === EXPRESSION_DATASOURCE_UID) delete m.datasource;
+    if (m.refId === out.refId) delete m.refId;
+    out.model = m;
+  }
+  return out;
+}
+
+const RULE_DEFAULTS: Json = { noDataState: "NoData", execErrState: "Alerting", for: "0s", keepFiringFor: "0s", isPaused: false, panelId: 0, dashboardUid: "" };
+
+function rule(r: Json): Json {
+  const out: Json = { ...r };
+  for (const [k, v] of Object.entries(RULE_DEFAULTS)) if (out[k] === v || out[k] === null) delete out[k];
+  if (out.for === "0") delete out.for;
+  if (out.keepFiringFor === "0") delete out.keepFiringFor;
+  for (const k of ["labels", "annotations"]) if (isEmpty(out[k])) delete out[k];
+  if (Array.isArray(out.data)) out.data = out.data.map((q) => (isObject(q) ? query(q) : q));
+  return out;
+}
+
+function byName(a: unknown, b: unknown): number {
+  const ka = isObject(a) ? `${String(a.folder ?? "")}\u0000${String(a.name ?? "")}` : "";
+  const kb = isObject(b) ? `${String(b.folder ?? "")}\u0000${String(b.name ?? "")}` : "";
+  return ka.localeCompare(kb);
+}
+
+/** The file in canonical form. */
+export function normalizeAlerting(file: Json): Json {
+  const out: Json = {};
+  if (file.apiVersion !== undefined) out.apiVersion = file.apiVersion;
+  if (Array.isArray(file.groups) && file.groups.length > 0) {
+    out.groups = file.groups
+      .map((g) => (isObject(g) ? { ...dropOrg(g), rules: Array.isArray(g.rules) ? g.rules.map((r) => (isObject(r) ? rule(r) : r)) : g.rules } : g))
+      .sort(byName);
+  }
+  if (Array.isArray(file.contactPoints) && file.contactPoints.length > 0) {
+    out.contactPoints = file.contactPoints
+      .map((c) =>
+        isObject(c)
+          ? {
+              ...dropOrg(c),
+              receivers: Array.isArray(c.receivers)
+                ? c.receivers.map((r) => {
+                    if (!isObject(r)) return r;
+                    const { disableResolveMessage, ...rest } = r;
+                    return disableResolveMessage === true ? r : rest;
+                  })
+                : c.receivers,
+            }
+          : c,
+      )
+      .sort(byName);
+  }
+  if (Array.isArray(file.policies) && file.policies.length > 0) out.policies = file.policies.map((p) => (isObject(p) ? dropOrg(p) : p));
+  if (Array.isArray(file.muteTimes) && file.muteTimes.length > 0) out.muteTimes = file.muteTimes.map((m) => (isObject(m) ? dropOrg(m) : m)).sort(byName);
+  if (Array.isArray(file.templates) && file.templates.length > 0) out.templates = file.templates.map((t) => (isObject(t) ? dropOrg(t) : t)).sort(byName);
+  return out;
+}

package/src/import/normalize.test.ts

@@ -0,0 +1,117 @@
+import { describe, expect, test } from "vitest";
+import { canonicalVariableUid, isBuiltinAnnotation, normalizeDashboard, refIdAt, splitValues } from "./normalize";
+import { applyEdits, pointer, pointerSegments } from "./edits";
+
+const prom = { type: "prometheus", uid: "prom" };
+
+describe("normalizeDashboard", () => {
+  test("keys at Grafana's default and the stored copy's bookkeeping are the same as no key", () => {
+    const stored = {
+      id: 12,
+      version: 4,
+      title: "T",
+      uid: "t",
+      editable: true,
+      graphTooltip: 0,
+      links: [],
+      tags: [],
+      time: { from: "now-6h", to: "now" },
+      timepicker: {},
+      timezone: "",
+      weekStart: "",
+      refresh: false,
+      annotations: { list: [] },
+      templating: { list: [] },
+      panels: [],
+    };
+    expect(normalizeDashboard(stored)).toEqual({ title: "T", uid: "t", panels: [] });
+  });
+
+  test("the built-in annotation, in any of the forms Grafana has written it, is no annotation", () => {
+    const base = { builtIn: 1, enable: true, hide: true, iconColor: "rgba(0, 211, 255, 1)", name: "Annotations & Alerts", type: "dashboard" };
+    for (const datasource of ["-- Grafana --", { type: "grafana", uid: "-- Grafana --" }, { type: "datasource", uid: "grafana" }, { uid: "-- Grafana --" }]) {
+      expect(isBuiltinAnnotation({ ...base, datasource })).toBe(true);
+    }
+    expect(isBuiltinAnnotation({ ...base, datasource: "-- Grafana --", target: { limit: 100, matchAny: false, tags: [], type: "dashboard" } })).toBe(true);
+    expect(isBuiltinAnnotation({ ...base, datasource: "-- Grafana --", enable: false })).toBe(false);
+    expect(isBuiltinAnnotation({ ...base, datasource: prom })).toBe(false);
+  });
+
+  test("a query without a datasource or refId gets its panel's and its position's", () => {
+    const d = normalizeDashboard({ panels: [{ type: "stat", datasource: { type: "prometheus", uid: "$ds" }, targets: [{ expr: "up" }, { expr: "down", refId: "" }] }] });
+    const ds = { type: "prometheus", uid: "${ds}" };
+    expect(d.panels).toEqual([
+      { type: "stat", datasource: ds, fieldConfig: { defaults: {}, overrides: [] }, targets: [{ expr: "up", datasource: ds, refId: "A" }, { expr: "down", datasource: ds, refId: "B" }] },
+    ]);
+  });
+
+  test("a panel's datasource is the one its queries share, whatever the panel says", () => {
+    const mixed = { type: "datasource", uid: "-- Mixed --" };
+    const [p] = normalizeDashboard({ panels: [{ type: "stat", datasource: mixed, targets: [{ refId: "A", datasource: prom }] }] }).panels as Array<{ datasource: unknown }>;
+    expect(p.datasource).toEqual(prom);
+  });
+
+  test("derived variable keys: options, a query variable's definition, a constant's current", () => {
+    const d = normalizeDashboard({
+      templating: {
+        list: [
+          { type: "query", name: "a", query: "q", definition: "q", refresh: 1, options: [{ text: "x", value: "x" }], current: {} },
+          { type: "query", name: "b", query: "q", refresh: 0, options: [{ text: "x", value: "x" }] },
+          { type: "custom", name: "c", query: "x, y", options: [] },
+          { type: "constant", name: "k", query: "v", hide: 2, current: { text: "v", value: "v" } },
+          { type: "textbox", name: "t", query: "v", current: { text: "v", value: "v", selected: false } },
+        ],
+      },
+    });
+    expect(d.templating).toEqual({
+      list: [
+        { type: "query", name: "a", query: "q" },
+        { type: "query", name: "b", query: "q", refresh: 0, options: [{ text: "x", value: "x" }] },
+        { type: "custom", name: "c", query: "x,y", current: { text: "x", value: "x" } },
+        { type: "constant", name: "k", query: "v" },
+        { type: "textbox", name: "t", query: "v" },
+      ],
+    });
+  });
+
+  test("nothing inside options is touched: a null there means something", () => {
+    const steps = [{ color: "green", value: null }];
+    const d = normalizeDashboard({ panels: [{ type: "stat", fieldConfig: { defaults: { thresholds: { steps } } } }] });
+    expect((d.panels as Array<{ fieldConfig: { defaults: unknown } }>)[0].fieldConfig.defaults).toEqual({ thresholds: { steps } });
+  });
+});
+
+describe("helpers", () => {
+  test("refIdAt", () => {
+    expect([0, 1, 25, 26, 27].map(refIdAt)).toEqual(["A", "B", "Z", "AA", "AB"]);
+  });
+
+  test("canonicalVariableUid", () => {
+    expect(["$ds", "${ds}", "[[ds]]", "${ds:raw}", "prom"].map(canonicalVariableUid)).toEqual(["${ds}", "${ds}", "${ds}", "${ds:raw}", "prom"]);
+  });
+
+  test("splitValues: commas, escaped commas and spaces", () => {
+    expect(splitValues("a, b\\,c ,, d")).toEqual(["a", "b,c", "d"]);
+  });
+});
+
+describe("applyEdits", () => {
+  test("substitutions, then replacements and removals by pointers into the original, then prepended variables", () => {
+    const source = { title: "${VAR}", panels: [{ id: 1 }, { id: 2, "a/b": 1 }, { id: 3 }], templating: { list: [{ name: "x" }] } };
+    const out = applyEdits(source, [
+      { op: "substitute", from: "${VAR}", to: "v" },
+      { op: "remove", path: "/panels/0" },
+      { op: "replace", path: pointer("panels", 1, "a/b"), value: 2 },
+      { op: "remove", path: "/panels/2" },
+      { op: "prependVariable", value: { name: "DS" } },
+    ]);
+    expect(out).toEqual({ title: "v", panels: [{ id: 2, "a/b": 2 }], templating: { list: [{ name: "DS" }, { name: "x" }] } });
+    // The source is left as it was.
+    expect(source.panels).toHaveLength(3);
+  });
+
+  test("pointers escape / and ~", () => {
+    expect(pointer("a/b", "c~d", 0)).toBe("/a~1b/c~0d/0");
+    expect(pointerSegments("/a~1b/c~0d/0")).toEqual(["a/b", "c~d", "0"]);
+  });
+});