@intentius/chant-lexicon-grafana 0.99.0 → 0.100.0

package/src/api/folders.ts

@@ -1,17 +1,19 @@
 /**
- * Folders, for the API applier (#2948). Every folder decision the applier
- * makes is in this module: which folders a build needs, the uid each gets,
- * how one is read, written, listed and deleted, and on which API.
+ * Folders: the one place a build's folders become uids and parents, and how
+ * the API applier (#2948) and observation read and write them.
  *
- * ## What the lexicon models today
+ * ## What a build declares
  *
- * A dashboard names its folder by title (`Dashboard.folder`), and a title
- * holds no nesting (the build flattens `/` in it). So the applier derives
- * one root-level folder per distinct title, with a stable uid made from the
- * title ({@link folderUidFor}), and a second apply finds it again by that
- * uid. {@link FolderPlan} already carries `parentUid`, and the writers
- * already send it, so #2953 (folder uid and nesting on the declaration) only
- * has to change {@link foldersForDashboards}.
+ * A dashboard names its folder as a path (`Dashboard.folder:
+ * "Platform/Kubernetes"`) or as a `Folder` (../folder.ts), and a `Folder`
+ * may be declared on its own. {@link resolveFolders} turns all of it into
+ * one {@link FolderPlan} per folder: every level of every path, the uid a
+ * `Folder` pins or {@link folderUidFor} of its path, and its parent's uid.
+ * The build calls it and writes the result to its index (`folders`, and a
+ * `folderUid` on each dashboard); the applier reads the index and calls it
+ * again, which also covers an index written before folders were listed.
+ * Two folders at one path with different uids, or two paths with one uid,
+ * throw: no delivery could make both.
  *
  * ## Which API
  *
@@ -25,7 +27,9 @@
  */
 
 import { GrafanaApiError, type GrafanaClient } from "./client";
-import { slugUid } from "../util";
+import { folderLevels, folderUidFor } from "../folder";
+
+export { folderUidFor };
 
 type Json = Record<string, unknown>;
 
@@ -55,6 +59,8 @@ export interface FolderPlan {
   readonly title: string;
   /** The parent folder's uid; absent for a root-level folder. */
   readonly parentUid?: string;
+  /** Its titles from the root, joined with `/`: the directory file provisioning reads it from. */
+  readonly path?: string;
 }
 
 /** A folder as Grafana holds it. */
@@ -64,6 +70,8 @@ export interface LiveFolder {
   readonly parentUid?: string;
   /** `metadata.labels`; empty on the legacy API. */
   readonly labels: Readonly<Record<string, string>>;
+  /** `metadata.annotations`; empty on the legacy API. */
+  readonly annotations?: Readonly<Record<string, string>>;
   readonly via: "apis" | "legacy";
   /** The request path it lives at. */
   readonly address: string;
@@ -71,31 +79,74 @@ export interface LiveFolder {
   readonly version?: number;
 }
 
-/**
- * The uid chant gives the folder a dashboard names by title. Stable, so a
- * second apply finds the folder the first one made; Grafana's own limit is
- * 40 characters, which `slugUid` keeps to.
- */
-export function folderUidFor(title: string): string {
-  return slugUid(title);
+/** The folders a build resolves to, and the uid of each path. */
+export interface ResolvedFolders {
+  /** One per folder, sorted by path, so a parent comes before its children. */
+  readonly folders: FolderPlan[];
+  /** The uid of the folder at `path` (any spelling `folderLevels` reads the same); undefined for the General folder. */
+  uidOf(path: string | undefined): string | undefined;
 }
 
 /**
- * The folders a set of dashboards needs, one per distinct title, sorted by
- * uid. The one place a dashboard's folder becomes a folder plan.
+ * Every folder a build needs, with its uid and parent: the folders declared
+ * with a uid (`Folder`s, or dashboards already resolved), and every level of
+ * every path a dashboard names. A level no declaration pins gets
+ * {@link folderUidFor} of its path. Throws when two declarations put
+ * different uids at one path, and when two paths would get one uid unless
+ * `duplicateUids` is `keep`: the build keeps both and GRAF104 reports them,
+ * since file provisioning, which gives folders uids of its own, can still
+ * deliver them.
  */
-export function foldersForDashboards(dashboards: Iterable<{ folder?: string }>): FolderPlan[] {
-  const byUid = new Map<string, FolderPlan>();
-  for (const d of dashboards) {
-    if (!d.folder) continue;
-    const uid = folderUidFor(d.folder);
-    const seen = byUid.get(uid);
-    if (seen && seen.title !== d.folder) {
-      throw new Error(`grafana apply: the folders "${seen.title}" and "${d.folder}" would both get the uid "${uid}"; rename one`);
+export function resolveFolders(
+  input: { declared?: Iterable<{ uid: string; path: string }>; paths?: Iterable<string | undefined> },
+  options: { duplicateUids?: "throw" | "keep" } = {},
+): ResolvedFolders {
+  const byPath = new Map<string, string>();
+  const key = (path: string) => folderLevels(path).join("/");
+  for (const d of input.declared ?? []) {
+    const path = key(d.path);
+    if (path === "") continue;
+    const prior = byPath.get(path);
+    if (prior !== undefined && prior !== d.uid) {
+      throw new Error(`grafana: the folder "${path}" is declared with the uids "${prior}" and "${d.uid}"; a folder has one uid`);
     }
-    byUid.set(uid, { uid, title: d.folder });
+    byPath.set(path, d.uid);
+  }
+  const addPath = (path: string) => {
+    const levels = folderLevels(path);
+    for (let i = 1; i <= levels.length; i++) {
+      const prefix = levels.slice(0, i).join("/");
+      if (!byPath.has(prefix)) byPath.set(prefix, folderUidFor(prefix));
+    }
+  };
+  for (const path of [...byPath.keys()]) addPath(path);
+  for (const path of input.paths ?? []) if (path) addPath(path);
+
+  const byUid = new Map<string, string>();
+  const folders: FolderPlan[] = [];
+  for (const path of [...byPath.keys()].sort((a, b) => a.localeCompare(b))) {
+    const uid = byPath.get(path)!;
+    const seen = byUid.get(uid);
+    if (seen !== undefined && options.duplicateUids !== "keep") throw new Error(`grafana: the folders "${seen}" and "${path}" would both get the uid "${uid}"; give one a Folder with its own uid`);
+    byUid.set(uid, path);
+    const levels = path.split("/");
+    const parentUid = levels.length > 1 ? byPath.get(levels.slice(0, -1).join("/")) : undefined;
+    folders.push({ uid, title: levels[levels.length - 1], ...(parentUid ? { parentUid } : {}), path });
   }
-  return [...byUid.values()].sort((a, b) => a.uid.localeCompare(b.uid));
+  return { folders, uidOf: (path) => (path === undefined ? undefined : byPath.get(key(path))) };
+}
+
+/**
+ * The folders a set of dashboards needs: every level of every folder they
+ * name, sorted by path. A dashboard that already carries its `folderUid`
+ * pins its folder's uid.
+ */
+export function foldersForDashboards(dashboards: Iterable<{ folder?: string; folderUid?: string }>): FolderPlan[] {
+  const list = [...dashboards];
+  return resolveFolders({
+    declared: list.filter((d) => d.folder && d.folderUid).map((d) => ({ uid: d.folderUid!, path: d.folder! })),
+    paths: list.map((d) => d.folder),
+  }).folders;
 }
 
 /** The folder API the server behind `client` serves, discovered once per client. */
@@ -120,12 +171,14 @@ export function folderPath(api: FolderApi, namespace: string, uid: string): stri
 function fromResource(resource: Json, address: string): LiveFolder {
   const metadata = isObject(resource.metadata) ? resource.metadata : {};
   const spec = isObject(resource.spec) ? resource.spec : {};
-  const parentUid = stringMap(metadata.annotations)[FOLDER_ANNOTATION];
+  const annotations = stringMap(metadata.annotations);
+  const parentUid = annotations[FOLDER_ANNOTATION];
   return {
     uid: typeof metadata.name === "string" ? metadata.name : "",
     title: typeof spec.title === "string" ? spec.title : "",
     ...(parentUid ? { parentUid } : {}),
     labels: stringMap(metadata.labels),
+    annotations,
     via: "apis",
     address,
   };
@@ -152,6 +205,27 @@ export async function readFolder(client: GrafanaClient, uid: string): Promise<Li
   return api.kind === "apis" ? fromResource(body, address) : fromLegacy(body, address);
 }
 
+/**
+ * The path of the folder with this uid, its titles from the root joined with
+ * `/`, the form `Dashboard.folder` takes. One read per folder per client;
+ * undefined when the folder, or one of its parents, cannot be found.
+ */
+export async function liveFolderPath(client: GrafanaClient, uid: string): Promise<string | undefined> {
+  const titles: string[] = [];
+  const seen = new Set<string>();
+  for (let at: string | undefined = uid; at; ) {
+    // Grafana's own limit on nesting is 8 levels; a longer chain is a cycle.
+    if (seen.has(at) || seen.size > 8) return undefined;
+    seen.add(at);
+    const id: string = at;
+    const folder = await client.once(`folder:${id}`, () => readFolder(client, id));
+    if (!folder) return undefined;
+    titles.unshift(folder.title);
+    at = folder.parentUid;
+  }
+  return titles.join("/");
+}
+
 /** Every folder in the organisation over `/apis`, paged. The legacy API has no labels to list by, so it is not listed. */
 export async function listFolders(client: GrafanaClient): Promise<LiveFolder[]> {
   const api = await folderApi(client);

package/src/build.test.ts

@@ -1,14 +1,19 @@
 import { describe, expect, test } from "vitest";
-import { Datasource } from "./datasource";
-import { Dashboard } from "./dashboard";
+import { Datasource, DatasourceProvisioning, ExternalDatasource } from "./datasource";
+import { Dashboard, DashboardProvider } from "./dashboard";
+import { Folder } from "./folder";
+import { load } from "js-yaml";
 import { Row, StatPanel, TextPanel, TimeSeriesPanel, TablePanel, definePanel } from "./panels";
 import { PromQuery, TempoQuery, LokiQuery, defineQuery } from "./query";
 import {
+  AdhocVariable,
   CustomVariable,
   ConstantVariable,
   DatasourceVariable,
+  GroupByVariable,
   IntervalVariable,
   QueryVariable,
+  SwitchVariable,
   TextboxVariable,
 } from "./variables";
 import { panelsJson, renderDashboard, variableModel, dashboardJson, grafanaFiles, buildGrafana, customVariableOptions, type PanelJson } from "./build";
@@ -302,6 +307,53 @@ describe("variables", () => {
     expect(variableModel(new TextboxVariable({ name: "q" }))).toMatchObject({ type: "textbox", query: "" });
   });
 
+  test("an object query is written as it is, its text as the definition", () => {
+    const query = { qryType: 1 as const, query: "label_values(up, job)", refId: "PrometheusVariableQueryEditor-VariableQuery" };
+    expect(variableModel(new QueryVariable({ name: "job", datasource: prometheus, query }))).toMatchObject({ query, definition: "label_values(up, job)" });
+    expect(variableModel(new QueryVariable({ name: "ns", datasource: prometheus, query: { namespace: "AWS/EC2" }, definition: "Namespaces" }))).toMatchObject({
+      query: { namespace: "AWS/EC2" },
+      definition: "Namespaces",
+    });
+  });
+
+  test("ad hoc, group by and switch variables as Grafana writes them", () => {
+    const ds = new DatasourceVariable({ name: "ds", pluginType: "prometheus" });
+    expect(variableModel(new AdhocVariable({ name: "f", datasource: ds, filters: [{ key: "ns", operator: "=", value: "shop" }] }))).toEqual({
+      type: "adhoc",
+      name: "f",
+      datasource: { type: "prometheus", uid: "${ds}" },
+      filters: [{ key: "ns", operator: "=", value: "shop" }],
+      baseFilters: [],
+    });
+    expect(variableModel(new GroupByVariable({ name: "by", datasource: prometheus, options: ["pod", { text: "Node", value: "node" }], defaultValue: ["pod"] }))).toEqual({
+      type: "groupby",
+      name: "by",
+      datasource: { type: "prometheus", uid: prometheus.uid },
+      options: [
+        { text: "pod", value: "pod" },
+        { text: "Node", value: "node" },
+      ],
+      current: { text: ["pod"], value: ["pod"] },
+      defaultValue: { text: ["pod"], value: ["pod"] },
+    });
+    expect(variableModel(new SwitchVariable({ name: "on" }))).toEqual({
+      type: "switch",
+      name: "on",
+      current: { text: "false", value: "false" },
+      options: [
+        { text: "true", value: "true" },
+        { text: "false", value: "false" },
+      ],
+    });
+    expect(variableModel(new SwitchVariable({ name: "q", enabled: true, enabledValue: "0.99", disabledValue: "0.5" }))).toMatchObject({
+      current: { text: "0.99", value: "0.99" },
+      options: [
+        { text: "0.99", value: "0.99" },
+        { text: "0.5", value: "0.5" },
+      ],
+    });
+  });
+
   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({
@@ -357,6 +409,10 @@ describe("variables", () => {
         new DatasourceVariable({ name: "ds", pluginType: "prometheus" }),
         new ConstantVariable({ name: "cluster", value: "x" }),
         new TextboxVariable({ name: "q", value: "y" }),
+        new QueryVariable({ name: "pods", datasource: prometheus, query: { qryType: 1, query: "label_values(kube_pod_info, pod)" } }),
+        new AdhocVariable({ name: "f", datasource: prometheus, baseFilters: [{ key: "cluster", operator: "=", value: "prod" }], defaultKeys: [{ text: "pod" }] }),
+        new GroupByVariable({ name: "by", datasource: prometheus, options: ["pod"] }),
+        new SwitchVariable({ name: "on", enabled: true }),
       ],
     });
     expect(validateDashboardSchema(renderDashboard(dash) as unknown as Record<string, unknown>)).toEqual([]);
@@ -366,16 +422,16 @@ describe("variables", () => {
 describe("extension points", () => {
   test("definePanel and defineQuery produce classes that render and lay out like built-ins", () => {
     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 OpenSearchQuery = defineQuery<{ query: string; refId?: string }>()({ datasourceType: "grafana-opensearch-datasource", className: "OpenSearchQuery" });
+    const os = new Datasource({ name: "Logs OS", type: "grafana-opensearch-datasource" });
     const json = renderDashboard(
-      new Dashboard({ title: "Custom", panels: [new ClockPanel({ options: { mode: "countdown" }, datasource: es, targets: [new ElasticQuery({ query: "*" })] })] }),
+      new Dashboard({ title: "Custom", panels: [new ClockPanel({ options: { mode: "countdown" }, datasource: os, targets: [new OpenSearchQuery({ query: "*" })] })] }),
     );
     expect(json.panels![0]).toMatchObject({
       type: "grafana-clock-panel",
       gridPos: { w: 8, h: 8, x: 0, y: 0 },
       options: { mode: "countdown" },
-      datasource: { type: "elasticsearch", uid: "logs-es" },
+      datasource: { type: "grafana-opensearch-datasource", uid: "logs-os" },
       targets: [{ refId: "A", query: "*" }],
     });
     expect(validateDashboardSchema(json as unknown as Record<string, unknown>)).toEqual([]);
@@ -413,3 +469,83 @@ describe("folders (#2944)", () => {
     expect(file(" / ")).toBe("dashboards/d.json");
   });
 });
+
+describe("folder uids and nesting (#2953)", () => {
+  const platform = new Folder({ title: "Platform", uid: "plat" });
+  const k8s = new Folder({ title: "Kubernetes", parent: platform });
+
+  test("a Folder is written where its path is, and the index lists every level with its uid and parent", () => {
+    const built = buildGrafana(
+      new Map<string, never>([
+        ["pods", new Dashboard({ title: "Pods", uid: "pods", folder: k8s }) as never],
+        ["nodes", new Dashboard({ title: "Nodes", uid: "nodes", folder: "Platform/Kubernetes/Nodes" }) as never],
+        ["spare", new Folder({ title: "Spare" }) as never],
+      ]),
+    );
+    expect(built.dashboards.map((d) => [d.file, d.folder, d.folderUid])).toEqual([
+      ["dashboards/Platform/Kubernetes/pods.json", "Platform/Kubernetes", "platform-kubernetes"],
+      ["dashboards/Platform/Kubernetes/Nodes/nodes.json", "Platform/Kubernetes/Nodes", "platform-kubernetes-nodes"],
+    ]);
+    expect(built.index.folders).toEqual([
+      { uid: "plat", title: "Platform", path: "Platform" },
+      { uid: "platform-kubernetes", title: "Kubernetes", parentUid: "plat", path: "Platform/Kubernetes" },
+      { uid: "platform-kubernetes-nodes", title: "Nodes", parentUid: "platform-kubernetes", path: "Platform/Kubernetes/Nodes" },
+      { uid: "spare", title: "Spare", path: "Spare" },
+    ]);
+  });
+
+  test("a path and a Folder at the same path are one folder; the Folder's uid wins", () => {
+    const built = buildGrafana([new Dashboard({ title: "A", uid: "a", folder: "Platform" }), new Dashboard({ title: "B", uid: "b", folder: platform })]);
+    expect(built.dashboards.map((d) => d.folderUid)).toEqual(["plat", "plat"]);
+    expect(built.folders).toEqual([{ uid: "plat", title: "Platform", path: "Platform" }]);
+  });
+
+  test("a Folder title is one level, and two uids at one path are refused", () => {
+    expect(() => new Folder({ title: "Platform/Kubernetes" })).toThrow(/not one folder level/);
+    expect(() => buildGrafana([new Folder({ title: "X", uid: "one" }), new Folder({ title: "X", uid: "two" })])).toThrow(/declared with the uids "one" and "two"/);
+  });
+
+  test("a root-level Folder on a DashboardProvider is written as folder and folderUid; a nested one is refused", () => {
+    const built = buildGrafana([new DashboardProvider({ name: "ops", folder: platform, path: "/d" })]);
+    expect(built.providers[0]).toMatchObject({ folder: "Platform", folderUid: "plat", options: { foldersFromFilesStructure: false } });
+    expect(() => new DashboardProvider({ name: "ops", folder: k8s })).toThrow(/nested; Grafana creates a provider's folder at the root/);
+  });
+});
+
+describe("annotations (#2953)", () => {
+  test("an annotation is written with its datasource resolved and Grafana's defaults filled in", () => {
+    const json = renderDashboard(
+      new Dashboard({
+        title: "D",
+        annotations: [
+          { name: "Deploys", datasource: prometheus, target: new PromQuery({ expr: "changes(up[5m]) > 0" }), titleFormat: "deploy" },
+          { name: "Incidents", datasource: { type: "grafana", uid: "-- Grafana --" }, enable: false, iconColor: "blue", target: { type: "tags", tags: ["incident"], limit: 100, matchAny: false } },
+        ],
+      }),
+    );
+    expect(json.annotations).toEqual({
+      list: [
+        { datasource: { type: "prometheus", uid: "prometheus" }, enable: true, iconColor: "red", name: "Deploys", titleFormat: "deploy", target: expect.objectContaining({ refId: "Anno", expr: "changes(up[5m]) > 0" }) },
+        { datasource: { type: "grafana", uid: "-- Grafana --" }, enable: false, iconColor: "blue", name: "Incidents", target: { type: "tags", tags: ["incident"], limit: 100, matchAny: false } },
+      ],
+    });
+    expect(validateDashboardSchema(json as never).filter((p) => p.severity === "error")).toEqual([]);
+    expect(renderDashboard(new Dashboard({ title: "E" })).annotations).toEqual({ list: [] });
+  });
+});
+
+describe("datasource prune (#2953)", () => {
+  const files = (entities: unknown[]) => load(buildGrafana(entities as never).files["provisioning/datasources/chant.yaml"] ?? "null") as Record<string, unknown> | null;
+
+  test("the datasource file prunes by default, so a removed Datasource leaves Grafana", () => {
+    expect(files([prometheus])).toMatchObject({ apiVersion: 1, prune: true });
+  });
+
+  test("DatasourceProvisioning turns pruning off and lists datasources to delete", () => {
+    const out = files([prometheus, new DatasourceProvisioning({ prune: false, deleteDatasources: [{ name: "Old" }, { name: "Other", orgId: 2 }] })]);
+    expect(out).toEqual({ apiVersion: 1, deleteDatasources: [{ name: "Old" }, { name: "Other", orgId: 2 }], datasources: [expect.objectContaining({ name: "Prometheus" })] });
+    expect(files([new DatasourceProvisioning({ deleteDatasources: [{ name: "Old" }] })])).toEqual({ apiVersion: 1, prune: true, deleteDatasources: [{ name: "Old" }], datasources: [] });
+    expect(files([new ExternalDatasource({ type: "prometheus", uid: "p" })])).toBeNull();
+    expect(() => buildGrafana([new DatasourceProvisioning({}), new DatasourceProvisioning({})])).toThrow(/at most one DatasourceProvisioning/);
+  });
+});