@intentius/chant-lexicon-grafana 0.97.0 → 0.99.0

package/src/validate-output.ts

@@ -1,23 +1,53 @@
 /**
- * The checks behind GRAF101-GRAF107, as plain functions over built Grafana
- * output: dashboard JSON documents and provisioned datasources. The
+ * The checks behind GRAF101-GRAF109, GRAF111-GRAF114 and GRAF115, as plain
+ * functions over built Grafana output: dashboard JSON documents, provisioned
+ * datasources, dashboard providers and alerting provisioning files (the
+ * alerting checks are in `validate-alerting.ts`). The
  * post-synth checks run them over a build; anything else holding the same
  * JSON (a test, another lexicon embedding dashboards) can call them directly.
  *
  * Checks that join a dashboard against datasources (GRAF101, GRAF102) only
- * see the datasources passed in. In a build that is the build root being
- * built (chant #1939): with no datasource declared in it they report
- * nothing, and a datasource declared in another build root looks undeclared.
+ * see the datasources passed in: the ones provisioned and the ones declared
+ * with `ExternalDatasource`. In a build that is the build root being built
+ * (chant #1939). With none declared they warn that references cannot be
+ * checked; a datasource that exists in Grafana but is not declared looks
+ * undeclared, so declare it with `ExternalDatasource`.
  */
 
-import type { ProvisionedDatasource } from "./build";
-import { GRID_COLUMNS } from "./build";
-import { BUILTIN_DATASOURCE_UIDS } from "./datasource";
+import type { ExternalDatasourceRecord, ProvisionedDatasource } from "./build";
+import { DASHBOARDS_DIR, GRID_COLUMNS } from "./build";
+import {
+  datasourceUses,
+  describePanel,
+  knownDatasources,
+  panelsOf,
+  variableReferences,
+  variablesOf,
+  type DatasourceRefJson,
+  type KnownDatasource,
+} from "./datasource-refs";
 import { isBuiltinVariable } from "./variables";
 import { isValidUid } from "./util";
 import { validateDashboardSchema } from "./schema-validate";
-
-export type GrafanaIssueCode = "GRAF101" | "GRAF102" | "GRAF103" | "GRAF104" | "GRAF105" | "GRAF106" | "GRAF107";
+import { checkGrafanaPromql, prometheusQueries } from "./promql-check";
+import { checkAlertingIdentity, checkNotificationRefs, checkRuleDatasources, checkRulePromql, checkRuleQueries, type AlertingDoc } from "./validate-alerting";
+import { closestGrafanaUnit, isGrafanaUnit } from "./spec/units";
+
+export type GrafanaIssueCode =
+  | "GRAF101"
+  | "GRAF102"
+  | "GRAF103"
+  | "GRAF104"
+  | "GRAF105"
+  | "GRAF106"
+  | "GRAF107"
+  | "GRAF108"
+  | "GRAF109"
+  | "GRAF111"
+  | "GRAF112"
+  | "GRAF113"
+  | "GRAF114"
+  | "GRAF115";
 
 export interface GrafanaIssue {
   code: GrafanaIssueCode;
@@ -35,57 +65,26 @@ export interface DashboardDoc {
 
 export interface GrafanaArtifacts {
   dashboards: DashboardDoc[];
+  /** Datasources the build provisions. */
   datasources: ProvisionedDatasource[];
+  /** Datasources the build references but does not provision (`ExternalDatasource`). */
+  externalDatasources?: ExternalDatasourceRecord[];
+  /** Entries of `providers:` in dashboard provisioning files, as written: any field may be missing. */
+  providers?: Array<Record<string, unknown>>;
+  /** Alerting provisioning files (rule groups, contact points, policies, mute timings, templates). */
+  alerting?: AlertingDoc[];
 }
 
-type Json = Record<string, unknown>;
-interface Ref {
-  type?: string;
-  uid?: string;
-}
+export type { AlertingDoc };
 
-interface PanelInfo {
-  panel: Json;
-  /** Panels inside a collapsed row are laid out in their own group. */
-  group: string;
-}
-
-function panelsOf(dashboard: Json): PanelInfo[] {
-  const out: PanelInfo[] = [];
-  const top = Array.isArray(dashboard.panels) ? (dashboard.panels as Json[]) : [];
-  for (const p of top) {
-    if (!p || typeof p !== "object") continue;
-    out.push({ panel: p, group: "" });
-    if (p.type === "row" && Array.isArray(p.panels)) {
-      for (const c of p.panels as Json[]) if (c && typeof c === "object") out.push({ panel: c, group: `row ${String(p.id)}` });
-    }
-  }
-  return out;
-}
+export { variableReferences };
 
-function describePanel(panel: Json): string {
-  const title = typeof panel.title === "string" && panel.title ? `"${panel.title}"` : "(untitled)";
-  return `panel ${title} (id ${String(panel.id ?? "?")})`;
-}
+type Json = Record<string, unknown>;
 
 function dashName(d: Json): string {
   return `Dashboard "${String(d.title ?? d.uid ?? "?")}"`;
 }
 
-function variablesOf(d: Json): Json[] {
-  const list = (d.templating as { list?: unknown } | undefined)?.list;
-  return Array.isArray(list) ? (list as Json[]).filter((v) => v && typeof v === "object") : [];
-}
-
-const VAR_REF = /\$\{([A-Za-z_][A-Za-z0-9_]*)(?::[^}]*)?\}|\[\[([A-Za-z_][A-Za-z0-9_]*)(?::[^\]]*)?\]\]|\$([A-Za-z_][A-Za-z0-9_]*)/g;
-
-/** Every variable name referenced in a string. */
-export function variableReferences(text: string): string[] {
-  const out: string[] = [];
-  for (const m of text.matchAll(VAR_REF)) out.push(m[1] ?? m[2] ?? m[3]);
-  return out;
-}
-
 function isVariableUid(uid: string | undefined): boolean {
   return typeof uid === "string" && uid.includes("$");
 }
@@ -101,79 +100,95 @@ function stringsIn(value: unknown, skip: ReadonlySet<string>, out: string[] = []
 
 const TARGET_SKIP = new Set(["refId", "datasource"]);
 
-/** Every datasource ref a panel makes, with where it is made. */
-function panelRefs(panel: Json): Array<{ ref: Ref; where: string }> {
-  const out: Array<{ ref: Ref; where: string }> = [];
-  const panelRef = panel.datasource as Ref | undefined;
+/** Every datasource ref a panel or row writes itself, with where it is written. */
+function panelRefs(panel: Json): Array<{ ref: DatasourceRefJson; where: string }> {
+  const out: Array<{ ref: DatasourceRefJson; where: string }> = [];
+  const panelRef = panel.datasource as DatasourceRefJson | undefined;
   if (panelRef && typeof panelRef === "object") out.push({ ref: panelRef, where: describePanel(panel) });
   const targets = Array.isArray(panel.targets) ? (panel.targets as Json[]) : [];
   for (const t of targets) {
-    const r = t?.datasource as Ref | undefined;
+    const r = t?.datasource as DatasourceRefJson | undefined;
     if (r && typeof r === "object") out.push({ ref: r, where: `${describePanel(panel)} query ${String(t.refId ?? "?")}` });
   }
   return out;
 }
 
-function isPseudoRef(ref: Ref): boolean {
-  return ref.type === "datasource" || ref.type === "grafana" || (ref.uid !== undefined && BUILTIN_DATASOURCE_UIDS.has(ref.uid));
+/** The datasources a set of artifacts knows by uid: provisioned and external. */
+export function knownDatasourcesOf(a: GrafanaArtifacts): Map<string, KnownDatasource> {
+  return knownDatasources(a.datasources, a.externalDatasources ?? []);
+}
+
+function listUids(known: ReadonlyMap<string, KnownDatasource>): string {
+  return [...known.keys()].map((k) => `"${k}"`).join(", ");
 }
 
 // ── GRAF101, GRAF102: datasource references ─────────────────────
 
 export function checkDatasourceRefs(a: GrafanaArtifacts): GrafanaIssue[] {
   const issues: GrafanaIssue[] = [];
-  if (a.datasources.length === 0) return issues; // declared elsewhere, or not at all: see #1939
-  const byUid = new Map(a.datasources.map((d) => [d.uid, d]));
+  const known = knownDatasourcesOf(a);
+  const types = new Set([...known.values()].map((k) => k.type));
   for (const { json: d } of a.dashboards) {
     const uid = String(d.uid ?? "");
-    const vars = new Map(variablesOf(d).map((v) => [String(v.name), v]));
-    const refs: Array<{ ref: Ref; where: string }> = [];
+    const push = (code: GrafanaIssueCode, severity: GrafanaIssue["severity"], message: string) =>
+      issues.push({ code, severity, message: `${dashName(d)} ${message}`, entity: uid });
+
     for (const { panel } of panelsOf(d)) {
       if (panel.type === "row") continue;
-      refs.push(...panelRefs(panel));
       const targets = Array.isArray(panel.targets) ? (panel.targets as Json[]) : [];
       if (targets.length > 0 && !panel.datasource && targets.every((t) => !t?.datasource)) {
-        issues.push({
-          code: "GRAF101",
-          severity: "warning",
-          message: `${dashName(d)} ${describePanel(panel)} has queries but no datasource; Grafana will send them to whichever datasource is its default.`,
-          entity: uid,
-        });
+        push("GRAF101", "warning", `${describePanel(panel)} has queries but no datasource; Grafana will send them to whichever datasource is its default.`);
       }
     }
-    for (const v of vars.values()) {
-      if (v.type === "query" && v.datasource && typeof v.datasource === "object") refs.push({ ref: v.datasource as Ref, where: `variable "${String(v.name)}"` });
+
+    const uses = datasourceUses(d, known).filter((u) => u.ref !== undefined);
+    const dsVariables = variablesOf(d).filter((v) => v.type === "datasource" && typeof v.query === "string" && v.query);
+
+    // Nothing declared: the references can't be checked. Say so once per dashboard rather than staying silent.
+    if (known.size === 0) {
+      const uids = [...new Set(uses.flatMap((u) => (u.resolved.kind === "undeclared" ? [u.resolved.uid] : [])))];
+      const plugins = [...new Set(dsVariables.map((v) => String(v.query)))];
+      const what = [
+        ...(uids.length > 0 ? [`datasource uid${uids.length > 1 ? "s" : ""} ${uids.map((u) => `"${u}"`).join(", ")}`] : []),
+        ...(plugins.length > 0 ? [`datasource variables of type ${plugins.join(", ")}`] : []),
+      ];
+      if (what.length > 0) {
+        const them = uids.length + plugins.length > 1 ? "them" : "it";
+        push(
+          "GRAF101",
+          "warning",
+          `uses ${what.join(" and ")}, but the build declares no datasource, so GRAF101 and GRAF102 cannot check ${them}. Declare a Datasource to provision one, or an ExternalDatasource for one that already exists in Grafana.`,
+        );
+      }
     }
-    for (const { ref, where } of refs) {
-      if (isPseudoRef(ref) || ref.uid === undefined) continue;
-      if (isVariableUid(ref.uid)) {
-        const [name] = variableReferences(ref.uid);
-        const v = name ? vars.get(name) : undefined;
-        if (v && v.type === "datasource" && ref.type && v.query && v.query !== ref.type) {
-          issues.push({
-            code: "GRAF102",
-            severity: "error",
-            message: `${dashName(d)} ${where} expects a ${ref.type} datasource, but variable "${name}" chooses among ${String(v.query)} datasources.`,
-            entity: uid,
-          });
+
+    for (const { ref, where, resolved } of uses) {
+      if (resolved.kind === "variable") {
+        const v = variablesOf(d).find((x) => x.name === resolved.variable);
+        if (v && v.type === "datasource" && ref!.type && v.query && v.query !== ref!.type) {
+          push("GRAF102", "error", `${where} expects a ${ref!.type} datasource, but variable "${resolved.variable}" chooses among ${String(v.query)} datasources.`);
         }
-        continue;
+      } else if (resolved.kind === "undeclared" && known.size > 0) {
+        push(
+          "GRAF101",
+          "error",
+          `${where} uses datasource uid "${resolved.uid}"${ref!.type ? ` (${ref!.type})` : ""}, which no declared Datasource or ExternalDatasource has. Declared: ${listUids(known)}.`,
+        );
+      } else if (resolved.kind === "declared" && ref!.type && ref!.type !== resolved.type) {
+        const ds = resolved.datasource;
+        push("GRAF102", "error", `${where} sends a ${ref!.type} query to ${ds.external ? "external " : ""}datasource "${ds.name ?? ds.uid}", which is ${ds.type}.`);
       }
-      const declared = byUid.get(ref.uid);
-      if (!declared) {
-        issues.push({
-          code: "GRAF101",
-          severity: "error",
-          message: `${dashName(d)} ${where} uses datasource uid "${ref.uid}"${ref.type ? ` (${ref.type})` : ""}, which no declared Datasource has. Declared: ${[...byUid.keys()].map((k) => `"${k}"`).join(", ")}.`,
-          entity: uid,
-        });
-      } else if (ref.type && ref.type !== declared.type) {
-        issues.push({
-          code: "GRAF102",
-          severity: "error",
-          message: `${dashName(d)} ${where} sends a ${ref.type} query to datasource "${declared.name}", which is ${declared.type}.`,
-          entity: uid,
-        });
+    }
+
+    // A datasource variable offers the datasources of its plugin type; with none declared it has nothing to choose.
+    if (known.size > 0) {
+      for (const v of dsVariables) {
+        if (types.has(String(v.query))) continue;
+        push(
+          "GRAF101",
+          "error",
+          `variable "${String(v.name)}" chooses among ${String(v.query)} datasources, but no declared Datasource or ExternalDatasource is of type ${String(v.query)}. Declared types: ${[...types].join(", ")}.`,
+        );
       }
     }
   }
@@ -235,7 +250,8 @@ export function checkDuplicates(a: GrafanaArtifacts): GrafanaIssue[] {
   for (const [uid, n] of dupes(a.dashboards, (d) => (typeof d.json.uid === "string" ? d.json.uid : undefined))) {
     push(`${n} dashboards share the uid "${uid}"; Grafana keeps one of them.`, uid);
   }
-  for (const [uid, n] of dupes(a.datasources, (d) => d.uid)) push(`${n} datasources share the uid "${uid}".`, uid);
+  const allUids = [...a.datasources.map((d) => d.uid), ...(a.externalDatasources ?? []).map((d) => d.uid)];
+  for (const [uid, n] of dupes(allUids, (u) => u)) push(`${n} datasources share the uid "${uid}".`, uid);
   for (const [name, n] of dupes(a.datasources, (d) => d.name)) push(`${n} datasources share the name "${name}"; Grafana needs names to be unique.`, name);
   for (const { json: d } of a.dashboards) {
     const uid = String(d.uid ?? "");
@@ -339,18 +355,33 @@ export function checkIdentity(a: GrafanaArtifacts): GrafanaIssue[] {
       });
     }
   }
+  for (const ds of a.externalDatasources ?? []) {
+    if (!isValidUid(ds.uid)) {
+      issues.push({
+        code: "GRAF106",
+        severity: "error",
+        message: `ExternalDatasource "${ds.name ?? ds.uid}" has uid "${ds.uid}"; Grafana accepts 1-40 letters, digits, "-" and "_".`,
+        entity: ds.name ?? ds.uid,
+      });
+    }
+  }
   return issues;
 }
 
 // ── GRAF107: the pinned schemas ─────────────────────────────────
 
+/**
+ * A value the pinned schemas (with the correction overlay) do not allow is
+ * an error; a key they do not know is a warning, since newer Grafana
+ * versions add keys the pin has not caught up with.
+ */
 export function checkSchema(a: GrafanaArtifacts): GrafanaIssue[] {
   const issues: GrafanaIssue[] = [];
   for (const { json: d } of a.dashboards) {
     for (const p of validateDashboardSchema(d)) {
       issues.push({
         code: "GRAF107",
-        severity: "error",
+        severity: p.severity,
         message: `${dashName(d)} ${p.path}: ${p.message} (Grafana schema).`,
         entity: String(d.uid ?? ""),
       });
@@ -359,6 +390,199 @@ export function checkSchema(a: GrafanaArtifacts): GrafanaIssue[] {
   return issues;
 }
 
+// ── GRAF108: PromQL syntax ──────────────────────────────────────
+
+/**
+ * Each panel query, query variable and alert rule query that reaches a
+ * Prometheus datasource is parsed as PromQL, with its template variables replaced by placeholders
+ * first (see `promql-check.ts`). A query whose datasource can't be told is
+ * not parsed.
+ */
+export function checkPromqlSyntax(a: GrafanaArtifacts): GrafanaIssue[] {
+  const issues: GrafanaIssue[] = [];
+  const known = knownDatasourcesOf(a);
+  for (const { json: d } of a.dashboards) {
+    for (const { where, expr } of prometheusQueries(d, known)) {
+      const checked = checkGrafanaPromql(expr);
+      if (checked.ok) continue;
+      issues.push({ code: "GRAF108", severity: "error", message: `${dashName(d)} ${where} is not valid PromQL: ${checked.message}.`, entity: String(d.uid ?? "") });
+    }
+  }
+  issues.push(...checkRulePromql(a.alerting ?? [], known));
+  return issues;
+}
+
+// ── GRAF115: units ──────────────────────────────────────────────
+
+/** Every unit a panel sets, with where: field defaults, `unit` overrides, heatmap axes and cells, and a legacy graph panel's y-axes. */
+export function panelUnits(panel: Json): Array<{ where: string; unit: string }> {
+  const out: Array<{ where: string; unit: string }> = [];
+  const add = (where: string, unit: unknown) => {
+    if (typeof unit === "string") out.push({ where, unit });
+  };
+  const fieldConfig = panel.fieldConfig as Json | undefined;
+  add("fieldConfig.defaults.unit", (fieldConfig?.defaults as Json | undefined)?.unit);
+  const overrides = Array.isArray(fieldConfig?.overrides) ? (fieldConfig.overrides as Json[]) : [];
+  overrides.forEach((o, i) => {
+    const props = Array.isArray(o?.properties) ? (o.properties as Json[]) : [];
+    props.forEach((p, j) => {
+      if (p?.id === "unit") add(`fieldConfig.overrides[${i}].properties[${j}]`, p.value);
+    });
+  });
+  const options = panel.options as Json | undefined;
+  add("options.yAxis.unit", (options?.yAxis as Json | undefined)?.unit);
+  add("options.cellValues.unit", (options?.cellValues as Json | undefined)?.unit);
+  if (Array.isArray(panel.yaxes)) (panel.yaxes as Json[]).forEach((y, i) => add(`yaxes[${i}].format`, y?.format));
+  return out;
+}
+
+/**
+ * A unit Grafana doesn't register (at v13.2.2) and that isn't a custom
+ * `<kind>:` unit is shown as a literal suffix, so `"byte"` renders `5 byte`.
+ * A warning: it renders, just not as meant.
+ */
+export function checkUnits(a: GrafanaArtifacts): GrafanaIssue[] {
+  const issues: GrafanaIssue[] = [];
+  for (const { json: d } of a.dashboards) {
+    const panels: Array<{ panel: Json; label: string }> = panelsOf(d).map(({ panel }) => ({ panel, label: describePanel(panel) }));
+    const elements = d.__elements;
+    if (elements && typeof elements === "object" && !Array.isArray(elements)) {
+      for (const [key, element] of Object.entries(elements as Json)) {
+        const model = element && typeof element === "object" ? (element as Json).model : undefined;
+        if (model && typeof model === "object" && !Array.isArray(model)) panels.push({ panel: model as Json, label: `library panel "${key}"` });
+      }
+    }
+    for (const { panel, label } of panels) {
+      if (panel.type === "row") continue;
+      for (const { where, unit } of panelUnits(panel)) {
+        if (isGrafanaUnit(unit)) continue;
+        const guess = closestGrafanaUnit(unit);
+        const hint = guess ? `Did you mean "${guess}"? ` : "";
+        issues.push({
+          code: "GRAF115",
+          severity: "warning",
+          message: `${dashName(d)} ${label} ${where}: unit "${unit}" is not one Grafana knows, so it is shown as a literal suffix. ${hint}For a custom unit write "suffix:${unit}" (or prefix:, si:, count:, currency:, time:).`,
+          entity: String(d.uid ?? ""),
+        });
+      }
+    }
+  }
+  return issues;
+}
+
+// ── GRAF109: where dashboard provisioning puts dashboards ───────
+
+/** Grafana's default `[folder] max_nested_folder_depth`, and the most it can be raised to. */
+const DEFAULT_FOLDER_DEPTH = 4;
+const MAX_FOLDER_DEPTH = 7;
+
+/** The folder levels a dashboard file sits in under `dashboards/`, e.g. `["Platform", "Kubernetes"]`. */
+function folderLevels(source: string | undefined): string[] {
+  if (!source?.startsWith(`${DASHBOARDS_DIR}/`)) return [];
+  return source.slice(DASHBOARDS_DIR.length + 1).split("/").slice(0, -1);
+}
+
+interface ProviderView {
+  name: string;
+  orgId: number;
+  path: string;
+  folder: string;
+  folderUid: string;
+  fromFiles: boolean;
+}
+
+function providerView(p: Record<string, unknown>): ProviderView {
+  const options = (p.options && typeof p.options === "object" ? p.options : {}) as Json;
+  const path = typeof options.path === "string" ? options.path : typeof options.folder === "string" ? options.folder : "";
+  return {
+    name: typeof p.name === "string" ? p.name : "?",
+    orgId: typeof p.orgId === "number" && p.orgId !== 0 ? p.orgId : 1,
+    path: path.replace(/\/+$/, "") || "/",
+    folder: typeof p.folder === "string" ? p.folder : "",
+    folderUid: typeof p.folderUid === "string" ? p.folderUid : "",
+    fromFiles: options.foldersFromFilesStructure === true,
+  };
+}
+
+/** Whether a provider reading `a` also reads `b`: Grafana walks a provider's path recursively. */
+function contains(a: string, b: string): boolean {
+  return a === b || a === "/" || b.startsWith(`${a}/`);
+}
+
+function listDashboards(ds: Array<{ d: Json; levels: string[] }>): string {
+  const shown = ds.slice(0, 3).map(({ d, levels }) => `"${String(d.title ?? d.uid ?? "?")}" (${levels.join("/")})`);
+  return ds.length > 3 ? `${shown.join(", ")} and ${ds.length - 3} more` : shown.join(", ");
+}
+
+export function checkProvisioning(a: GrafanaArtifacts): GrafanaIssue[] {
+  const issues: GrafanaIssue[] = [];
+  const push = (severity: GrafanaIssue["severity"], message: string, entity?: string) => issues.push({ code: "GRAF109", severity, message, entity });
+  const providers = (a.providers ?? []).map(providerView);
+  const foldered = a.dashboards.map(({ source, json }) => ({ d: json, levels: folderLevels(source) })).filter((x) => x.levels.length > 0);
+
+  // Two providers reading the same files, in the same org.
+  for (let i = 0; i < providers.length; i++) {
+    for (let j = i + 1; j < providers.length; j++) {
+      const [p, q] = [providers[i], providers[j]];
+      if (p.orgId !== q.orgId) continue;
+      const shared = contains(p.path, q.path) ? q.path : contains(q.path, p.path) ? p.path : undefined;
+      if (shared === undefined) continue;
+      push(
+        "error",
+        `Dashboard providers "${p.name}" and "${q.name}" both load the dashboards under ${shared}. Grafana provisions each of them twice, then takes database writes away from both providers, so later changes to the files never reach Grafana. Give each provider its own path.`,
+        q.name,
+      );
+    }
+  }
+
+  // A provider mapping directories to folders that also names a folder.
+  for (const p of providers) {
+    if (!p.fromFiles || (p.folder === "" && p.folderUid === "")) continue;
+    if (p.folder !== "" && p.folderUid !== "") {
+      push("error", `Dashboard provider "${p.name}" sets folder, folderUid and foldersFromFilesStructure; Grafana refuses to start it. Drop folder and folderUid, or foldersFromFilesStructure.`, p.name);
+    } else {
+      const which = p.folder !== "" ? `folder "${p.folder}"` : `folderUid "${p.folderUid}"`;
+      push(
+        "warning",
+        `Dashboard provider "${p.name}" sets ${which} and foldersFromFilesStructure. Grafana files each dashboard by its directory and the top-level ones in General, so ${which} is not used${p.folderUid !== "" ? " (before Grafana 13.1 every directory resolves to that one folder uid instead)" : ""}. Drop one of the two.`,
+        p.name,
+      );
+    }
+  }
+
+  // Dashboards with a folder that no provider maps from directories.
+  if (foldered.length > 0 && providers.length > 0 && !providers.some((p) => p.fromFiles)) {
+    const where = providers.map((p) => `"${p.name}" puts every dashboard in ${p.folder !== "" ? `folder "${p.folder}"` : p.folderUid !== "" ? `folder uid "${p.folderUid}"` : "General"}`).join("; ");
+    push(
+      "warning",
+      `${foldered.length === 1 ? "A dashboard declares a folder" : `${foldered.length} dashboards declare a folder`}, ${listDashboards(foldered)}, but no dashboard provider sets foldersFromFilesStructure: ${where}. Set foldersFromFilesStructure: true on the provider (and drop its folder), or leave the dashboards' folder out.`,
+    );
+  }
+
+  // Nested folders, where a provider does map directories to folders.
+  if (providers.some((p) => p.fromFiles)) {
+    for (const { d, levels } of foldered) {
+      if (levels.length < 2) continue;
+      const uid = String(d.uid ?? "");
+      const path = levels.join("/");
+      if (levels.length > MAX_FOLDER_DEPTH) {
+        push("error", `${dashName(d)} is in folder "${path}", ${levels.length} levels deep; Grafana nests at most ${MAX_FOLDER_DEPTH}, and the provider stops with an error when it reaches it.`, uid);
+      } else {
+        const depth =
+          levels.length > DEFAULT_FOLDER_DEPTH
+            ? ` It is ${levels.length} levels deep, past Grafana's default max_nested_folder_depth of ${DEFAULT_FOLDER_DEPTH}: raise it in [folder], or the provider stops with an error when it reaches it.`
+            : "";
+        push(
+          "warning",
+          `${dashName(d)} is in nested folder "${path}". Grafana 13.1 and later create the folders inside one another; Grafana 12.4 and 13.0 use only the last level and put it in a top-level folder "${levels[levels.length - 1]}".${depth}`,
+          uid,
+        );
+      }
+    }
+  }
+  return issues;
+}
+
 const BY_CODE: Record<GrafanaIssueCode, (a: GrafanaArtifacts) => GrafanaIssue[]> = {
   GRAF101: (a) => checkDatasourceRefs(a).filter((i) => i.code === "GRAF101"),
   GRAF102: (a) => checkDatasourceRefs(a).filter((i) => i.code === "GRAF102"),
@@ -367,6 +591,13 @@ const BY_CODE: Record<GrafanaIssueCode, (a: GrafanaArtifacts) => GrafanaIssue[]>
   GRAF105: checkGrid,
   GRAF106: checkIdentity,
   GRAF107: checkSchema,
+  GRAF108: checkPromqlSyntax,
+  GRAF109: checkProvisioning,
+  GRAF111: (a) => checkRuleQueries(a.alerting ?? []),
+  GRAF112: (a) => checkRuleDatasources(a.alerting ?? [], knownDatasourcesOf(a)),
+  GRAF113: (a) => checkNotificationRefs(a.alerting ?? []),
+  GRAF114: (a) => checkAlertingIdentity(a.alerting ?? []),
+  GRAF115: checkUnits,
 };
 
 /** The issues one check finds. */

package/src/validate.ts

@@ -23,6 +23,7 @@ export type { ValidateCheck, ValidateResult } from "@intentius/chant/codegen/val
 export const REQUIRED_NAMES = [
   "Dashboard",
   "Datasource",
+  "ExternalDatasource",
   "DashboardProvider",
   "Row",
   "TimeSeriesPanel",
@@ -33,6 +34,19 @@ export const REQUIRED_NAMES = [
   "TracesPanel",
   "HeatmapPanel",
   "TextPanel",
+  "BarChartPanel",
+  "BarGaugePanel",
+  "PieChartPanel",
+  "StateTimelinePanel",
+  "StatusHistoryPanel",
+  "HistogramPanel",
+  "NodeGraphPanel",
+  "XYChartPanel",
+  "TrendPanel",
+  "CanvasPanel",
+  "GeomapPanel",
+  "FlameGraphPanel",
+  "AlertListPanel",
   "PromQuery",
   "TempoQuery",
   "LokiQuery",

package/src/variables.ts

@@ -11,7 +11,7 @@
 
 import { createProperty } from "@intentius/chant/runtime";
 import type { Declarable } from "@intentius/chant/declarable";
-import type { DatasourceEntity, DatasourceRef } from "./datasource";
+import type { DatasourceEntity, DatasourceRef, ExternalDatasourceEntity } from "./datasource";
 import type { VariableOption } from "./schema/dashboard.gen";
 
 export type VariableKind = "query" | "custom" | "interval" | "datasource" | "constant" | "textbox";
@@ -40,7 +40,7 @@ interface MultiValueProps {
 
 /** A variable anything can hold before its datasource is known: its own datasource ref or a datasource variable. */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type VariableDatasource = DatasourceEntity<any> | DatasourceRef | DatasourceVariableEntity<any>;
+export type VariableDatasource = DatasourceEntity<any> | ExternalDatasourceEntity<any> | DatasourceRef | DatasourceVariableEntity<any>;
 
 export interface QueryVariableProps extends CommonVariableProps, MultiValueProps {
   datasource: VariableDatasource;
@@ -54,6 +54,11 @@ export interface QueryVariableProps extends CommonVariableProps, MultiValueProps
 }
 
 export interface CustomVariableProps extends CommonVariableProps, MultiValueProps {
+  /**
+   * The values, in Grafana's syntax: `"Production : prod"` shows
+   * `Production` and sets `prod`. A comma is part of the value (written as
+   * `\,`, and one already escaped is kept).
+   */
   values: string[];
 }