@intentius/chant-lexicon-grafana 0.97.0 → 0.99.0

package/src/api/library-panels.ts

@@ -0,0 +1,101 @@
+/**
+ * Library panels, for the API applier (#2948).
+ *
+ * A dashboard that uses a library panel holds only a reference to it
+ * (`{ libraryPanel: { uid, name } }`); the panel itself lives in Grafana's
+ * library, and an exported dashboard carries its model in `__elements`,
+ * keyed by uid. The applier writes each element to the library over
+ * `/api/library-elements` before the dashboards that reference it, and
+ * sends the dashboards without `__elements`, `__inputs` or `__requires`,
+ * which are export-only keys Grafana does not store.
+ *
+ * The library elements API is the same on Grafana 11, 12.4 and 13.2. It has
+ * no labels, so a library panel cannot carry chant's marker and is never
+ * pruned (the applier reports that as `not-prunable`). An update needs the
+ * element's current `version`, which the read supplies.
+ */
+
+import type { GrafanaClient } from "./client";
+import { send } from "./folders";
+import { converged } from "./converge";
+
+type Json = Record<string, unknown>;
+
+function isObject(v: unknown): v is Json {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** `kind` of a library panel in the library elements API (2 is a library variable). */
+export const LIBRARY_PANEL_KIND = 1;
+
+/** Keys an exported dashboard carries that Grafana does not store. */
+export const EXPORT_ONLY_KEYS: readonly string[] = ["__elements", "__inputs", "__requires"];
+
+/** One library panel a build needs. */
+export interface LibraryPanelPlan {
+  readonly uid: string;
+  readonly name: string;
+  readonly model: Json;
+  /** The folder it goes in: that of the first dashboard that carries it. Absent for the General folder. */
+  readonly folderUid?: string;
+}
+
+/**
+ * The library panels in a dashboard's `__elements`. An element that is not a
+ * panel (a library variable), or that has no uid, name or model, is not
+ * something the library panel API can take; it is returned in `skipped`.
+ */
+export function libraryPanelsOf(dashboard: Json, folderUid?: string): { panels: LibraryPanelPlan[]; skipped: string[] } {
+  const elements = dashboard.__elements;
+  const panels: LibraryPanelPlan[] = [];
+  const skipped: string[] = [];
+  if (!isObject(elements)) return { panels, skipped };
+  for (const [key, el] of Object.entries(elements)) {
+    if (!isObject(el)) {
+      skipped.push(key);
+      continue;
+    }
+    const uid = typeof el.uid === "string" && el.uid !== "" ? el.uid : key;
+    const kind = el.kind ?? LIBRARY_PANEL_KIND;
+    if (kind !== LIBRARY_PANEL_KIND || typeof el.name !== "string" || !isObject(el.model)) {
+      skipped.push(uid);
+      continue;
+    }
+    panels.push({ uid, name: el.name, model: el.model, ...(folderUid ? { folderUid } : {}) });
+  }
+  return { panels, skipped };
+}
+
+/** A dashboard without the export-only keys, as the applier sends it. */
+export function withoutExportKeys(dashboard: Json): Json {
+  const out: Json = { ...dashboard };
+  for (const k of EXPORT_ONLY_KEYS) delete out[k];
+  return out;
+}
+
+export function libraryPanelPath(uid: string): string {
+  return `/api/library-elements/${encodeURIComponent(uid)}`;
+}
+
+/**
+ * Create or update one library panel. Unchanged when its name, folder and
+ * model already match; nothing is written then.
+ */
+export async function ensureLibraryPanel(
+  client: GrafanaClient,
+  plan: LibraryPanelPlan,
+): Promise<{ action: "created" | "updated" | "unchanged"; address: string }> {
+  const address = libraryPanelPath(plan.uid);
+  const live = (await client.get<{ result?: Json }>(address))?.result;
+  const body = { name: plan.name, kind: LIBRARY_PANEL_KIND, model: plan.model, folderUid: plan.folderUid ?? "" };
+  if (!live) {
+    await send(client, "POST", "/api/library-elements", { uid: plan.uid, ...body });
+    return { action: "created", address };
+  }
+  const liveFolder = typeof live.folderUid === "string" ? live.folderUid : "";
+  if (live.name === plan.name && liveFolder === (plan.folderUid ?? "") && converged(plan.model, live.model)) {
+    return { action: "unchanged", address };
+  }
+  await send(client, "PATCH", address, { ...body, version: typeof live.version === "number" ? live.version : 1 });
+  return { action: "updated", address };
+}

package/src/build.test.ts

@@ -11,13 +11,14 @@ import {
   QueryVariable,
   TextboxVariable,
 } from "./variables";
-import { panelsJson, renderDashboard, variableModel, dashboardJson, grafanaFiles, type PanelJson } from "./build";
+import { panelsJson, renderDashboard, variableModel, dashboardJson, grafanaFiles, buildGrafana, customVariableOptions, type PanelJson } from "./build";
 
 /** The panels array, read as plain panels (the tests below build no rows unless they say so). */
 function panelsOnly(items: Parameters<typeof panelsJson>[0]): PanelJson[] {
   return panelsJson(items) as PanelJson[];
 }
 import { validateDashboardSchema } from "./schema-validate";
+import { checkGrid } from "./validate-output";
 
 const prometheus = new Datasource({ name: "Prometheus", type: "prometheus" });
 const tempo = new Datasource({ name: "Tempo", type: "tempo" });
@@ -77,6 +78,138 @@ describe("layout", () => {
     expect((panels[1] as unknown as { panels: unknown[] }).panels).toEqual([]);
   });
 
+  test("a row with a y keeps that line, even over an empty band or on a line a panel takes (#2992)", () => {
+    const panels = panelsJson([
+      new StatPanel({ title: "a", gridPos: { x: 0, y: 0, w: 24, h: 4 } }),
+      new Row({ title: "late", gridPos: { y: 6 }, panels: [new StatPanel({ title: "b", gridPos: { x: 0, y: 7, w: 24, h: 4 } })] }),
+      new Row({ title: "auto", panels: [new StatPanel({ title: "c" })] }),
+      new Row({ title: "early", gridPos: { y: 8 } }),
+    ]);
+    expect(panels.map((p) => [p.title, p.gridPos])).toEqual([
+      ["a", { h: 4, w: 24, x: 0, y: 0 }],
+      ["late", { h: 1, w: 24, x: 0, y: 6 }],
+      ["b", { h: 4, w: 24, x: 0, y: 7 }],
+      // An auto-placed row skips the line the "early" row reserved.
+      ["auto", { h: 1, w: 24, x: 0, y: 11 }],
+      ["c", { h: 4, w: 6, x: 0, y: 12 }],
+      ["early", { h: 1, w: 24, x: 0, y: 8 }],
+    ]);
+  });
+
+  test("an auto-placed panel flows around an explicit one declared before it (#2941)", () => {
+    const panels = panelsJson([
+      new TimeSeriesPanel({ title: "a", gridPos: { x: 0, y: 0, w: 12 } }),
+      new TimeSeriesPanel({ title: "b", gridPos: { w: 12 } }),
+    ]);
+    expect(panels.map((p) => p.gridPos)).toEqual([
+      { h: 8, w: 12, x: 0, y: 0 },
+      { h: 8, w: 12, x: 12, y: 0 },
+    ]);
+  });
+
+  test("an explicit panel reserves its cells even when declared after auto-placed ones", () => {
+    const panels = panelsJson([
+      new StatPanel({ title: "s1" }),
+      new StatPanel({ title: "s2" }),
+      new StatPanel({ title: "s3" }),
+      new StatPanel({ title: "s4" }),
+      new StatPanel({ title: "pinned", gridPos: { x: 6, y: 0, w: 6, h: 4 } }),
+      new TextPanel({ title: "wide" }),
+    ]);
+    expect(panels.map((p) => [p.title, p.gridPos])).toEqual([
+      ["s1", { h: 4, w: 6, x: 0, y: 0 }],
+      ["s2", { h: 4, w: 6, x: 12, y: 0 }],
+      ["s3", { h: 4, w: 6, x: 18, y: 0 }],
+      ["s4", { h: 4, w: 6, x: 0, y: 4 }],
+      ["pinned", { h: 4, w: 6, x: 6, y: 0 }],
+      ["wide", { h: 3, w: 24, x: 0, y: 8 }],
+    ]);
+  });
+
+  test("a line blocked by an explicit panel is skipped", () => {
+    const panels = panelsJson([
+      new StatPanel({ title: "band", gridPos: { x: 0, y: 0, w: 24, h: 2 } }),
+      new StatPanel({ title: "hole", gridPos: { x: 0, y: 6, w: 6, h: 2 } }),
+      new StatPanel({ title: "s1" }),
+      new TextPanel({ title: "wide" }),
+    ]);
+    expect(panels.map((p) => [p.title, p.gridPos])).toEqual([
+      ["band", { h: 2, w: 24, x: 0, y: 0 }],
+      ["hole", { h: 2, w: 6, x: 0, y: 6 }],
+      ["s1", { h: 4, w: 6, x: 0, y: 2 }],
+      ["wide", { h: 3, w: 24, x: 0, y: 8 }],
+    ]);
+  });
+
+  test("a partial gridPos is honoured: x only keeps its column, y only its line", () => {
+    const panels = panelsJson([
+      new StatPanel({ title: "right", gridPos: { x: 18 } }),
+      new StatPanel({ title: "left", gridPos: { x: 0 } }),
+      new StatPanel({ title: "next" }),
+      new StatPanel({ title: "low", gridPos: { y: 20, w: 12 } }),
+      new StatPanel({ title: "low2", gridPos: { y: 20, w: 12 } }),
+      new StatPanel({ title: "low3", gridPos: { y: 20, w: 12 } }),
+    ]);
+    expect(panels.map((p) => [p.title, p.gridPos])).toEqual([
+      ["right", { h: 4, w: 6, x: 18, y: 0 }],
+      ["left", { h: 4, w: 6, x: 0, y: 4 }],
+      ["next", { h: 4, w: 6, x: 6, y: 4 }],
+      ["low", { h: 4, w: 12, x: 0, y: 20 }],
+      ["low2", { h: 4, w: 12, x: 12, y: 20 }],
+      ["low3", { h: 4, w: 12, x: 0, y: 24 }],
+    ]);
+  });
+
+  test("a full-width row header skips lines taken by explicit panels", () => {
+    const panels = panelsJson([
+      new TimeSeriesPanel({ title: "top" }),
+      new Row({
+        title: "open",
+        panels: [new StatPanel({ title: "pinned", gridPos: { x: 0, y: 8, w: 24, h: 2 } }), new StatPanel({ title: "a" })],
+      }),
+      new Row({ title: "next" }),
+    ]);
+    expect(panels.map((p) => [p.type, p.title, p.gridPos])).toEqual([
+      ["timeseries", "top", { h: 8, w: 12, x: 0, y: 0 }],
+      ["row", "open", { h: 1, w: 24, x: 0, y: 10 }],
+      ["stat", "pinned", { h: 2, w: 24, x: 0, y: 8 }],
+      ["stat", "a", { h: 4, w: 6, x: 0, y: 11 }],
+      ["row", "next", { h: 1, w: 24, x: 0, y: 15 }],
+    ]);
+  });
+
+  test("a collapsed row's panels flow around its own explicit panels and don't block the dashboard", () => {
+    const panels = panelsJson([
+      new Row({
+        title: "shut",
+        collapsed: true,
+        panels: [new StatPanel({ title: "pinned", gridPos: { x: 0, y: 1, w: 6, h: 4 } }), new StatPanel({ title: "a" })],
+      }),
+      new StatPanel({ title: "after" }),
+    ]);
+    const shut = panels[0] as unknown as { panels: PanelJson[] };
+    expect(shut.panels.map((p) => [p.title, p.gridPos])).toEqual([
+      ["pinned", { h: 4, w: 6, x: 0, y: 1 }],
+      ["a", { h: 4, w: 6, x: 6, y: 1 }],
+    ]);
+    expect(panels[1].gridPos).toEqual({ h: 4, w: 6, x: 0, y: 1 });
+  });
+
+  test("a mixed layout built by the dashboard passes GRAF105", () => {
+    const dash = new Dashboard({
+      title: "Mixed",
+      panels: [
+        new TimeSeriesPanel({ title: "a", gridPos: { x: 0, y: 0, w: 12 } }),
+        new TimeSeriesPanel({ title: "b", gridPos: { w: 12 } }),
+        new StatPanel({ title: "c", gridPos: { x: 6 } }),
+        new StatPanel({ title: "d", gridPos: { x: 12, y: 8, w: 12, h: 4 } }),
+        new StatPanel({ title: "e" }),
+        new Row({ title: "r", panels: [new StatPanel({ title: "f", gridPos: { x: 18, y: 12 } }), new StatPanel({ title: "g" })] }),
+      ],
+    });
+    expect(checkGrid({ dashboards: [{ json: JSON.parse(dashboardJson(dash)) }], datasources: [] })).toEqual([]);
+  });
+
   test("auto ids skip ids set explicitly", () => {
     const panels = panelsJson([new StatPanel(), new StatPanel({ id: 1 }), new StatPanel()]);
     expect(panels.map((p) => p.id)).toEqual([2, 1, 3]);
@@ -102,6 +235,17 @@ describe("datasources and targets", () => {
     ]);
   });
 
+  test("a panel declared Mixed stays Mixed, and a query naming no datasource is not sent to Mixed (#2992)", () => {
+    const mixed = { type: "datasource", uid: "-- Mixed --" };
+    const [bare, panel] = panelsOnly([
+      new TextPanel({ datasource: mixed }),
+      new StatPanel({ datasource: mixed, targets: [new PromQuery({ expr: "up", datasource: prometheus }), new PromQuery({ expr: "down" })] }),
+    ]);
+    expect(bare.datasource).toEqual(mixed);
+    expect(panel.datasource).toEqual(mixed);
+    expect(panel.targets!.map((t) => (t as { datasource?: unknown }).datasource)).toEqual([{ type: "prometheus", uid: "prometheus" }, undefined]);
+  });
+
   test("a panel takes its queries' shared datasource, and a row passes its own down", () => {
     const [shared] = panelsOnly([new StatPanel({ targets: [new PromQuery({ expr: "up", datasource: prometheus })] })]);
     expect(shared.datasource).toEqual({ type: "prometheus", uid: "prometheus" });
@@ -158,6 +302,51 @@ describe("variables", () => {
     expect(variableModel(new TextboxVariable({ name: "q" }))).toMatchObject({ type: "textbox", query: "" });
   });
 
+  test("a custom value in Grafana's `text : value` syntax shows the text and sets the value (#2944)", () => {
+    const v = variableModel(new CustomVariable({ name: "env", values: ["Production : prod", "Staging : stg", "dev"] }));
+    expect(v).toMatchObject({
+      query: "Production : prod,Staging : stg,dev",
+      current: { text: "Production", value: "prod" },
+      options: [
+        { selected: true, text: "Production", value: "prod" },
+        { selected: false, text: "Staging", value: "stg" },
+        { selected: false, text: "dev", value: "dev" },
+      ],
+    });
+  });
+
+  test("a custom value's selected option follows current by value, and multi-value current selects several", () => {
+    const v = variableModel(
+      new CustomVariable({ name: "env", multi: true, values: ["Production : prod", "Staging : stg"], current: { text: ["Staging"], value: ["stg"] } }),
+    );
+    expect((v as { options: Array<{ selected: boolean }> }).options.map((o) => o.selected)).toEqual([false, true]);
+  });
+
+  test("a comma already escaped as \\, is not escaped again (#2944)", () => {
+    const v = variableModel(new CustomVariable({ name: "pair", values: ["a\\,b", "c,d", "Label, with comma : x\\,y"] }));
+    expect(v).toMatchObject({
+      query: "a\\,b,c\\,d,Label\\, with comma : x\\,y",
+      options: [
+        { text: "a,b", value: "a,b" },
+        { text: "c,d", value: "c,d" },
+        { text: "Label, with comma", value: "x,y" },
+      ],
+    });
+  });
+
+  test("customVariableOptions parses a query the way Grafana does", () => {
+    expect(customVariableOptions("a : 1, b,c\\,d , ,x:y, k : v : w")).toEqual([
+      { text: "a", value: "1" },
+      { text: "b", value: "b" },
+      { text: "c,d", value: "c,d" },
+      { text: "", value: "" },
+      // No spaces around the colon: one plain value.
+      { text: "x:y", value: "x:y" },
+      // Grafana's first group is greedy: the last ` : ` splits.
+      { text: "k : v", value: "w" },
+    ]);
+  });
+
   test("a dashboard with every variable kind matches the dashboard schema", () => {
     const dash = new Dashboard({
       title: "Vars",
@@ -176,16 +365,16 @@ describe("variables", () => {
 
 describe("extension points", () => {
   test("definePanel and defineQuery produce classes that render and lay out like built-ins", () => {
-    const PieChartPanel = definePanel<{ pieType?: "pie" | "donut" }>()({ type: "piechart", className: "PieChartPanel", defaultSize: { w: 8, h: 8 } });
+    const ClockPanel = definePanel<{ mode?: "time" | "countdown" }>()({ type: "grafana-clock-panel", className: "ClockPanel", defaultSize: { w: 8, h: 8 } });
     const ElasticQuery = defineQuery<{ query: string; refId?: string }>()({ datasourceType: "elasticsearch", className: "ElasticQuery" });
     const es = new Datasource({ name: "Logs ES", type: "elasticsearch" });
     const json = renderDashboard(
-      new Dashboard({ title: "Custom", panels: [new PieChartPanel({ options: { pieType: "donut" }, datasource: es, targets: [new ElasticQuery({ query: "*" })] })] }),
+      new Dashboard({ title: "Custom", panels: [new ClockPanel({ options: { mode: "countdown" }, datasource: es, targets: [new ElasticQuery({ query: "*" })] })] }),
     );
     expect(json.panels![0]).toMatchObject({
-      type: "piechart",
+      type: "grafana-clock-panel",
       gridPos: { w: 8, h: 8, x: 0, y: 0 },
-      options: { pieType: "donut" },
+      options: { mode: "countdown" },
       datasource: { type: "elasticsearch", uid: "logs-es" },
       targets: [{ refId: "A", query: "*" }],
     });
@@ -208,3 +397,19 @@ describe("extension points", () => {
     ]);
   });
 });
+
+describe("folders (#2944)", () => {
+  test("a nested folder is written as nested directories under dashboards/", () => {
+    const built = buildGrafana([new Dashboard({ title: "Pods", uid: "pods", folder: "Platform/Kubernetes" })]);
+    expect(built.dashboards[0].file).toBe("dashboards/Platform/Kubernetes/pods.json");
+    expect(built.index.dashboards[0].folder).toBe("Platform/Kubernetes");
+  });
+
+  test("blank levels, dot-led levels and backslashes can't leave dashboards/", () => {
+    const file = (folder: string) => buildGrafana([new Dashboard({ title: "D", uid: "d", folder })]).dashboards[0].file;
+    expect(file("/Platform//Kubernetes/")).toBe("dashboards/Platform/Kubernetes/d.json");
+    expect(file("../../etc")).toBe("dashboards/etc/d.json");
+    expect(file("a\\b")).toBe("dashboards/a-b/d.json");
+    expect(file(" / ")).toBe("dashboards/d.json");
+  });
+});