@intentius/chant-lexicon-grafana 0.98.0 → 0.100.0

package/src/validate-output.ts

@@ -1,23 +1,55 @@
 /**
- * The checks behind GRAF101-GRAF107, as plain functions over built Grafana
- * output: dashboard JSON documents and provisioned datasources. The
+ * The checks behind GRAF101-GRAF110, 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 { isBuiltinVariable } from "./variables";
+import type { ExternalDatasourceRecord, ProvisionedDatasource } from "./build";
+import { DASHBOARDS_DIR, GRID_COLUMNS } from "./build";
+import {
+  annotationsOf,
+  datasourceUses,
+  describePanel,
+  knownDatasources,
+  panelsOf,
+  variableReferences,
+  variablesOf,
+  type DatasourceRefJson,
+  type KnownDatasource,
+} from "./datasource-refs";
+import { isBuiltinVariable, MULTI_VALUE_KINDS } from "./variables";
 import { isValidUid } from "./util";
-import { validateDashboardSchema } from "./schema-validate";
-
-export type GrafanaIssueCode = "GRAF101" | "GRAF102" | "GRAF103" | "GRAF104" | "GRAF105" | "GRAF106" | "GRAF107";
+import { schemaValidationUnavailable, validateDashboardSchema } from "./schema-validate";
+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"
+  | "GRAF110"
+  | "GRAF111"
+  | "GRAF112"
+  | "GRAF113"
+  | "GRAF114"
+  | "GRAF115";
 
 export interface GrafanaIssue {
   code: GrafanaIssueCode;
@@ -35,57 +67,30 @@ 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[];
+  /** The folders the build resolved (its index's `folders`): each level of each dashboard's folder path, and every `Folder`. */
+  folders?: Array<{ uid: string; title: string; path?: string; parentUid?: string }>;
+  /** `deleteDatasources` entries of datasource provisioning files. */
+  deleteDatasources?: Array<{ name: string; orgId?: number }>;
 }
 
-type Json = Record<string, unknown>;
-interface Ref {
-  type?: string;
-  uid?: string;
-}
-
-interface PanelInfo {
-  panel: Json;
-  /** Panels inside a collapsed row are laid out in their own group. */
-  group: string;
-}
+export type { AlertingDoc };
 
-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 +106,108 @@ 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,
-        });
+    }
+
+    // An ExternalDatasource the provisioning file deletes (and does not provision again) is gone once Grafana provisions it.
+    const deleted = new Set((a.deleteDatasources ?? []).filter((x) => (x.orgId ?? 1) === 1).map((x) => x.name));
+    const provisioned = new Set(a.datasources.map((x) => x.name));
+    const gone = new Set([...known.values()].filter((k) => k.external && k.name !== undefined && deleted.has(k.name) && !provisioned.has(k.name)).map((k) => k.uid));
+    for (const { where, resolved } of uses) {
+      if (resolved.kind !== "declared" || !gone.has(resolved.datasource.uid)) continue;
+      push(
+        "GRAF101",
+        "error",
+        `${where} uses external datasource "${resolved.datasource.name}", which the datasource provisioning file deletes (deleteDatasources); Grafana removes it before the dashboard can use it.`,
+      );
+    }
+
+    // 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(", ")}.`,
+        );
       }
     }
   }
@@ -210,10 +244,22 @@ export function checkVariables(a: GrafanaArtifacts): GrafanaIssue[] {
       }
     }
     for (const v of variablesOf(d)) {
+      const ref = v.datasource as DatasourceRefJson | undefined;
+      if (ref && typeof ref === "object" && isVariableUid(ref.uid)) {
+        for (const n of variableReferences(ref.uid!)) if (n !== v.name) report(n, `variable "${String(v.name)}" datasource`);
+      }
       if (v.type !== "query") continue;
-      const names = new Set(stringsIn(v.query, new Set()).flatMap(variableReferences));
+      const names = new Set(stringsIn(v.query, new Set(["refId"])).flatMap(variableReferences));
       for (const n of names) if (n !== v.name) report(n, `variable "${String(v.name)}" query`);
     }
+    for (const an of annotationsOf(d)) {
+      const where = `annotation "${String(an.name ?? "?")}"`;
+      const ref = an.datasource as DatasourceRefJson | undefined;
+      if (ref && typeof ref === "object" && isVariableUid(ref.uid)) for (const n of variableReferences(ref.uid!)) report(n, `${where} datasource`);
+      // Grafana interpolates the query (`target`, or Prometheus's legacy `expr`), not the name, colour or title formats.
+      const names = new Set(stringsIn([an.target, an.expr], TARGET_SKIP).flatMap(variableReferences));
+      for (const n of names) report(n, `${where} query`);
+    }
   }
   return issues;
 }
@@ -235,8 +281,13 @@ 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 [uid, n] of dupes(a.folders ?? [], (f) => f.uid)) {
+    const paths = (a.folders ?? []).filter((f) => f.uid === uid).map((f) => `"${f.path ?? f.title}"`);
+    push(`${n} folders share the uid "${uid}" (${paths.join(", ")}); Grafana keeps one folder per uid, so the API applier refuses the build. Give one a Folder with its own uid.`, uid);
+  }
   for (const { json: d } of a.dashboards) {
     const uid = String(d.uid ?? "");
     const panels = panelsOf(d).map((p) => p.panel);
@@ -339,18 +390,51 @@ export function checkIdentity(a: GrafanaArtifacts): GrafanaIssue[] {
       });
     }
   }
+  for (const f of a.folders ?? []) {
+    const where = `Folder "${f.path ?? f.title}"`;
+    if (!isValidUid(f.uid)) {
+      issues.push({ code: "GRAF106", severity: "error", message: `${where} has uid "${f.uid}"; Grafana accepts 1-40 letters, digits, "-" and "_".`, entity: f.uid });
+    } else if (f.uid === "general") {
+      issues.push({
+        code: "GRAF106",
+        severity: "error",
+        message: `${where} has uid "general", which Grafana keeps for its root (the General folder) and refuses for a folder. Leave folder out to put a dashboard in General, or give the folder another uid.`,
+        entity: f.uid,
+      });
+    }
+  }
+  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[] = [];
+  if (a.dashboards.length === 0) return issues;
+  const unavailable = schemaValidationUnavailable();
+  if (unavailable) {
+    return [{ code: "GRAF107", severity: "warning", message: `Dashboards were not checked against the Grafana schema: ${unavailable}.` }];
+  }
   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 +443,237 @@ 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;
+}
+
+// ── GRAF110: repeats ────────────────────────────────────────────
+
+/**
+ * A panel or row repeated over a variable Grafana cannot repeat over, or
+ * one that can only ever hold one value. Grafana repeats over a query,
+ * custom, datasource or group by variable (a `MultiValueVariable` in
+ * @grafana/scenes), once per selected value. Over any other kind it logs an
+ * error and shows the panel once; over a query, custom or datasource
+ * variable with neither `multi` nor `includeAll`, there is only ever one
+ * value to repeat for. A repeat naming no variable is GRAF103's.
+ */
+const KIND_NAMES: Readonly<Record<string, string>> = { adhoc: "an ad hoc", interval: "an interval", groupby: "a group by" };
+
+export function checkRepeats(a: GrafanaArtifacts): GrafanaIssue[] {
+  const issues: GrafanaIssue[] = [];
+  for (const { json: d } of a.dashboards) {
+    const variables = new Map(variablesOf(d).map((v) => [String(v.name), v]));
+    for (const { panel } of panelsOf(d)) {
+      if (typeof panel.repeat !== "string" || panel.repeat === "") continue;
+      const v = variables.get(panel.repeat);
+      if (!v) continue;
+      const where = panel.type === "row" ? `row "${String(panel.title ?? "")}"` : describePanel(panel);
+      const type = String(v.type);
+      const kind = `${KIND_NAMES[type] ?? `a ${type}`} variable`;
+      let why: string | undefined;
+      if (!MULTI_VALUE_KINDS.has(type)) {
+        why = `${kind}, which Grafana cannot repeat over: it shows the ${panel.type === "row" ? "row" : "panel"} once. Repeat over a query, custom, datasource or group by variable`;
+      } else if (type !== "groupby" && v.multi !== true && v.includeAll !== true) {
+        why = `${kind} with neither multi nor includeAll, so it only ever holds one value and the ${panel.type === "row" ? "row" : "panel"} shows once. Set multi or includeAll on it`;
+      }
+      if (why) {
+        issues.push({ code: "GRAF110", severity: "warning", message: `${dashName(d)} ${where} repeats over $${panel.repeat}, ${why}.`, entity: String(d.uid ?? "") });
+      }
+    }
+  }
+  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 +682,14 @@ const BY_CODE: Record<GrafanaIssueCode, (a: GrafanaArtifacts) => GrafanaIssue[]>
   GRAF105: checkGrid,
   GRAF106: checkIdentity,
   GRAF107: checkSchema,
+  GRAF108: checkPromqlSyntax,
+  GRAF109: checkProvisioning,
+  GRAF110: checkRepeats,
+  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. */