@intentius/chant-lexicon-grafana 0.97.0 → 0.99.0

package/src/k8s.ts

@@ -0,0 +1,197 @@
+/**
+ * Grafana dashboards and provisioning delivered to Kubernetes as ConfigMaps
+ * (#2954), from `@intentius/chant-lexicon-grafana/k8s`.
+ *
+ * `GrafanaConfigMaps` writes one ConfigMap per dashboard and one for the
+ * datasource provisioning file, labelled the way the Grafana Helm chart's
+ * sidecar (kiwigrid/k8s-sidecar, also in kube-prometheus-stack) finds them:
+ * `grafana_dashboard: "1"` and `grafana_datasource: "1"`. A dashboard's
+ * folder goes in the `k8s-sidecar-target-directory` annotation the sidecar
+ * reads by default. Each dashboard ConfigMap holds `<uid>.json`, the same
+ * text as `dashboardJson(dashboard)`, which is also what the k8s importer
+ * turns such a ConfigMap back into (#2962).
+ *
+ * A Grafana run without the sidecar (a plain Deployment, as in
+ * `examples/agent-observability`) mounts the same ConfigMaps with
+ * `grafanaVolumes()`, which also needs the dashboard provider file that
+ * `GrafanaConfigMaps` writes to a third ConfigMap. The provisioning files go
+ * under `/etc/grafana/provisioning` and each dashboard folder is a volume of
+ * its own under the provider's path: inside a ConfigMap volume a
+ * subdirectory is a symlink, and Grafana's dashboard provider does not
+ * follow symlinked directories.
+ *
+ * This module is the only part of the grafana lexicon that loads the k8s
+ * lexicon; nothing else imports it.
+ */
+
+import { Composite, type CompositeInstance } from "@intentius/chant/composite";
+import type { Declarable } from "@intentius/chant/declarable";
+import { ConfigMap } from "@intentius/chant-lexicon-k8s/generated/index";
+import { buildGrafana, DASHBOARD_PROVIDERS_FILE, DASHBOARDS_DIR, DATASOURCES_FILE } from "./build";
+import { DEFAULT_DASHBOARDS_PATH } from "./dashboard";
+
+/** The label the Grafana Helm chart's sidecar looks for on dashboard ConfigMaps (`sidecar.dashboards.label`). */
+export const SIDECAR_DASHBOARD_LABEL = "grafana_dashboard";
+/** The label it looks for on datasource ConfigMaps (`sidecar.datasources.label`). */
+export const SIDECAR_DATASOURCE_LABEL = "grafana_datasource";
+/** The annotation the sidecar reads a dashboard's target directory from, by default (its `FOLDER_ANNOTATION`). */
+export const SIDECAR_FOLDER_ANNOTATION = "k8s-sidecar-target-directory";
+
+/** Where Grafana reads provisioning files. */
+export const GRAFANA_PROVISIONING_PATH = "/etc/grafana/provisioning";
+
+export interface GrafanaConfigMapsProps {
+  /** The grafana declarations to deliver: dashboards, datasources, `DashboardProvider`s. Anything else is ignored. */
+  entities: Iterable<Declarable>;
+  namespace?: string;
+  /** Prefix of every ConfigMap name. Defaults to `grafana`. */
+  name?: string;
+  /** Labels added to every ConfigMap, beside the sidecar's. */
+  labels?: Record<string, string>;
+  /** The dashboard label as `[key, value]`, or `false` for none. Defaults to `["grafana_dashboard", "1"]`. */
+  dashboardLabel?: readonly [string, string] | false;
+  /** The datasource label as `[key, value]`, or `false` for none. Defaults to `["grafana_datasource", "1"]`. */
+  datasourceLabel?: readonly [string, string] | false;
+  /** The annotation holding a dashboard's folder, or `false` for none. Defaults to `k8s-sidecar-target-directory`. */
+  folderAnnotation?: string | false;
+}
+
+/** The `metadata.name` of each ConfigMap, and which file it holds. */
+export interface GrafanaConfigMapLayout {
+  dashboards: Array<{ configMap: string; key: string; folder: string; uid: string; text: string }>;
+  datasources?: { configMap: string; key: string; text: string };
+  providers?: { configMap: string; key: string; text: string };
+}
+
+/** A DNS-1123 subdomain made from a name: lower case, `[a-z0-9-.]`, at most 253 characters. */
+function dnsName(text: string): string {
+  const out = text
+    .toLowerCase()
+    .replace(/[^a-z0-9.-]+/g, "-")
+    .replace(/^[^a-z0-9]+|[^a-z0-9]+$/g, "");
+  return (out || "x").slice(0, 253).replace(/[^a-z0-9]+$/, "");
+}
+
+function basename(path: string): string {
+  return path.slice(path.lastIndexOf("/") + 1);
+}
+
+/** Which ConfigMap each file goes in, and under which key. `GrafanaConfigMaps` and `grafanaVolumes` both read it. */
+export function grafanaConfigMapLayout(props: Pick<GrafanaConfigMapsProps, "entities" | "name">): GrafanaConfigMapLayout {
+  const prefix = props.name ?? "grafana";
+  const built = buildGrafana(props.entities);
+  const taken = new Set<string>();
+  const unique = (base: string) => {
+    let out = base;
+    for (let n = 2; taken.has(out); n++) out = `${base}-${n}`;
+    taken.add(out);
+    return out;
+  };
+  const layout: GrafanaConfigMapLayout = {
+    dashboards: built.dashboards.map((d) => {
+      const dir = d.file.slice(DASHBOARDS_DIR.length + 1, d.file.lastIndexOf("/") + 1).replace(/\/$/, "");
+      return { configMap: unique(dnsName(`${prefix}-dashboard-${d.uid}`)), key: basename(d.file), folder: dir, uid: d.uid, text: built.files[d.file] };
+    }),
+  };
+  if (built.files[DATASOURCES_FILE] !== undefined) {
+    layout.datasources = { configMap: unique(dnsName(`${prefix}-datasources`)), key: basename(DATASOURCES_FILE), text: built.files[DATASOURCES_FILE] };
+  }
+  if (built.files[DASHBOARD_PROVIDERS_FILE] !== undefined) {
+    layout.providers = { configMap: unique(dnsName(`${prefix}-dashboard-providers`)), key: basename(DASHBOARD_PROVIDERS_FILE), text: built.files[DASHBOARD_PROVIDERS_FILE] };
+  }
+  return layout;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type ConfigMapEntity = InstanceType<typeof ConfigMap> & Declarable;
+
+export type GrafanaConfigMapsMembers = Record<string, ConfigMapEntity>;
+export type GrafanaConfigMapsInstance = CompositeInstance<GrafanaConfigMapsMembers> & GrafanaConfigMapsMembers;
+
+/** A member name from a ConfigMap name: `grafana-dashboard-red` becomes `dashboardRed`. */
+function memberName(configMap: string, prefix: string): string {
+  const rest = configMap.startsWith(`${prefix}-`) ? configMap.slice(prefix.length + 1) : configMap;
+  const words = rest.split(/[^A-Za-z0-9]+/).filter(Boolean);
+  return words.map((w, i) => (i === 0 ? w : w.charAt(0).toUpperCase() + w.slice(1))).join("") || "configMap";
+}
+
+/**
+ * One ConfigMap per dashboard, one for the datasources and one for the
+ * dashboard provider, labelled for the Grafana sidecar. Export the result
+ * from a k8s build root; the members are named after the ConfigMaps
+ * (`dashboardGenaiAgents`, `datasources`, `dashboardProviders`).
+ */
+export const GrafanaConfigMaps = Composite<GrafanaConfigMapsProps, GrafanaConfigMapsMembers>((props) => {
+  const prefix = dnsName(props.name ?? "grafana");
+  const layout = grafanaConfigMapLayout({ ...props, name: prefix });
+  const dashboardLabel = props.dashboardLabel === undefined ? ([SIDECAR_DASHBOARD_LABEL, "1"] as const) : props.dashboardLabel;
+  const datasourceLabel = props.datasourceLabel === undefined ? ([SIDECAR_DATASOURCE_LABEL, "1"] as const) : props.datasourceLabel;
+  const folderAnnotation = props.folderAnnotation === undefined ? SIDECAR_FOLDER_ANNOTATION : props.folderAnnotation;
+
+  const metadata = (name: string, label: readonly [string, string] | false, annotations?: Record<string, string>) => ({
+    name,
+    ...(props.namespace ? { namespace: props.namespace } : {}),
+    labels: { ...(props.labels ?? {}), ...(label ? { [label[0]]: label[1] } : {}) },
+    ...(annotations ? { annotations } : {}),
+  });
+
+  const members: GrafanaConfigMapsMembers = {};
+  for (const d of layout.dashboards) {
+    const annotations = folderAnnotation && d.folder ? { [folderAnnotation]: d.folder } : undefined;
+    members[memberName(d.configMap, prefix)] = new ConfigMap({ metadata: metadata(d.configMap, dashboardLabel, annotations), data: { [d.key]: d.text } }) as ConfigMapEntity;
+  }
+  for (const f of [layout.datasources, layout.providers]) {
+    if (!f) continue;
+    const label = f === layout.datasources ? datasourceLabel : false;
+    members[memberName(f.configMap, prefix)] = new ConfigMap({ metadata: metadata(f.configMap, label), data: { [f.key]: f.text } }) as ConfigMapEntity;
+  }
+  return members;
+}, "GrafanaConfigMaps");
+
+export interface GrafanaVolumesOptions {
+  /** Where the dashboard provider reads dashboards. Defaults to `/var/lib/grafana/dashboards`, the provider chant writes by default. */
+  dashboardsPath?: string;
+  /** Prefix of the volume names. Defaults to `grafana`. */
+  volumeName?: string;
+}
+
+export interface GrafanaVolumes {
+  volumes: Array<Record<string, unknown>>;
+  volumeMounts: Array<{ name: string; mountPath: string; readOnly: true }>;
+}
+
+/**
+ * The pod volumes and container mounts that put `GrafanaConfigMaps`'s files
+ * where a Grafana without the sidecar reads them: the provisioning files
+ * under `/etc/grafana/provisioning`, and each dashboard folder under the
+ * provider's path, one projected volume per folder. Pass the same `entities`
+ * and `name` as to `GrafanaConfigMaps`.
+ */
+export function grafanaVolumes(props: Pick<GrafanaConfigMapsProps, "entities" | "name">, options: GrafanaVolumesOptions = {}): GrafanaVolumes {
+  const prefix = dnsName(props.name ?? "grafana");
+  const layout = grafanaConfigMapLayout({ ...props, name: prefix });
+  const vol = dnsName(options.volumeName ?? prefix);
+  const root = (options.dashboardsPath ?? DEFAULT_DASHBOARDS_PATH).replace(/\/+$/, "");
+  const volumes: GrafanaVolumes["volumes"] = [];
+  const volumeMounts: GrafanaVolumes["volumeMounts"] = [];
+
+  const provisioning = [
+    ...(layout.datasources ? [{ configMap: { name: layout.datasources.configMap, items: [{ key: layout.datasources.key, path: `datasources/${layout.datasources.key}` }] } }] : []),
+    ...(layout.providers ? [{ configMap: { name: layout.providers.configMap, items: [{ key: layout.providers.key, path: `dashboards/${layout.providers.key}` }] } }] : []),
+  ];
+  if (provisioning.length > 0) {
+    volumes.push({ name: `${vol}-provisioning`, projected: { sources: provisioning } });
+    volumeMounts.push({ name: `${vol}-provisioning`, mountPath: GRAFANA_PROVISIONING_PATH, readOnly: true });
+  }
+
+  const folders = [...new Set(layout.dashboards.map((d) => d.folder))].sort();
+  folders.forEach((folder, i) => {
+    const name = `${vol}-dashboards-${i}`;
+    const sources = layout.dashboards
+      .filter((d) => d.folder === folder)
+      .map((d) => ({ configMap: { name: d.configMap, items: [{ key: d.key, path: d.key }] } }));
+    volumes.push({ name, projected: { sources } });
+    volumeMounts.push({ name, mountPath: folder ? `${root}/${folder}` : root, readOnly: true });
+  });
+  return { volumes, volumeMounts };
+}

package/src/lint/audit-catalog.ts

@@ -2,7 +2,8 @@
  * The grafana lexicon's chant audit catalog, contributed via
  * `grafanaPlugin.auditCatalog()` (#687, #1346).
  *
- * GRAF101-GRAF107 read the emitted dashboard JSON and provisioning files, so
+ * GRAF101-GRAF109, GRAF111-GRAF114 and GRAF115 read the emitted dashboard
+ * JSON and provisioning files (alerting included), so
  * they fire on an audit of files chant didn't build too, and are
  * `yamlBased`. GRAF001 and GRAF002 read TypeScript source, so they are
  * constructed with `yamlBased: false`; they are listed for a reader who
@@ -25,7 +26,7 @@ export const grafanaAuditCatalog: Record<string, RuleMeta> = {
   GRAF002: sourceRule(
     "GRAF002",
     "security",
-    "Datasource secret declared as a literal",
+    "Datasource or contact point secret declared as a literal",
     "Replace the value with `$__env{NAME}` or `$__file{/path}` so Grafana reads it when it loads the provisioning file.",
   ),
   GRAF101: auditRule(
@@ -33,7 +34,7 @@ export const grafanaAuditCatalog: Record<string, RuleMeta> = {
     "merge-worthy",
     "guidance",
     "Panel uses an undeclared datasource",
-    "Point the panel or query at a declared Datasource, or declare the datasource it names in the same build root.",
+    "Point the panel or query at a declared Datasource, or declare the datasource it names in the same build root: a Datasource to provision it, an ExternalDatasource if it already exists in Grafana.",
     { category: "correctness" },
   ),
   GRAF102: auditRule(
@@ -84,4 +85,60 @@ export const grafanaAuditCatalog: Record<string, RuleMeta> = {
     "Fix the key or value the message names; the panel option types generated from the same schema show what is allowed.",
     { category: "correctness" },
   ),
+  GRAF108: auditRule(
+    "GRAF108",
+    "merge-worthy",
+    "guidance",
+    "Query sent to Prometheus is not valid PromQL",
+    "Fix the expression at the offset the message names: an unbalanced bracket or quote, a bad range duration, a missing operator. Template variables are substituted before the check, so $var, ${var} and $__rate_interval are fine where Grafana accepts them.",
+    { category: "correctness" },
+  ),
+  GRAF109: auditRule(
+    "GRAF109",
+    "merge-worthy",
+    "guidance",
+    "Dashboard provisioning puts a dashboard somewhere other than its declared folder, or loads it twice",
+    "Give each dashboard provider its own path; set foldersFromFilesStructure: true (and no folder) on the provider when dashboards declare a folder; for a nested folder, run Grafana 13.1 or later or use a single-level folder.",
+    { category: "correctness" },
+  ),
+  GRAF111: auditRule(
+    "GRAF111",
+    "merge-worthy",
+    "guidance",
+    "Alert rule condition, expression input or refId does not fit the rule's queries",
+    "Point the condition, each expression's input and record.from at a refId the rule has, give each query its own refId, and fix the expression field the message names.",
+    { category: "correctness" },
+  ),
+  GRAF112: auditRule(
+    "GRAF112",
+    "merge-worthy",
+    "guidance",
+    "Alert rule queries an undeclared datasource, or one of another type",
+    "Pass a declared Datasource or ExternalDatasource as the query's datasource, of the type its model is for.",
+    { category: "correctness" },
+  ),
+  GRAF113: auditRule(
+    "GRAF113",
+    "merge-worthy",
+    "guidance",
+    "Alerting routes to an undeclared contact point or mute timing, or a matcher does not parse",
+    "Declare the ContactPoint or MuteTiming (or pass the entity itself rather than its name), and write matchers as [label, op, value] with op =, !=, =~ or !~.",
+    { category: "correctness" },
+  ),
+  GRAF114: auditRule(
+    "GRAF114",
+    "merge-worthy",
+    "guidance",
+    "Alerting uid, name, title or interval Grafana rejects, or declared twice",
+    'Use 1-40 letters, digits, "-" and "_" for uids, a multiple of 10s for group intervals, and one name per rule group, contact point, mute timing and template in each organisation.',
+    { category: "correctness" },
+  ),
+  GRAF115: auditRule(
+    "GRAF115",
+    "merge-worthy",
+    "guidance",
+    "Panel unit Grafana doesn't know",
+    'Use a unit id from Grafana\'s unit picker ("bytes", "s", "percent", "reqps"), or a custom unit such as "suffix: cores", "prefix:$", "si:mF", "count:reqs" or "currency:EUR". Grafana shows an unknown unit as a literal suffix.',
+    { category: "correctness" },
+  ),
 };

package/src/lint/core-lint.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from "vitest";
+import { copyFileSync, mkdtempSync, mkdirSync, rmSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { lintCommand } from "@intentius/chant/cli/commands/lint";
+import { build } from "@intentius/chant/build";
+import { grafanaPlugin } from "../plugin";
+import { grafanaSerializer } from "../serializer";
+import { BUILTIN_CATALOG } from "../catalog";
+
+// The fixture carries no chant.config of its own, which would make it a
+// project in the repo's workspace proposal; the lint test gives it one in a
+// temporary directory.
+const fixture = join(import.meta.dirname, "..", "..", "test", "fixtures", "inline-dashboard");
+
+describe("core lint on grafana's property-kind declarables (chant #2957)", () => {
+  it("names every panel, row, query and variable class property-kind, and no resource", () => {
+    const names = grafanaPlugin.propertyClassNames!();
+    expect(names).toEqual(expect.arrayContaining(["TimeSeriesPanel", "StatPanel", "Row", "PromQuery", "LokiQuery", "QueryVariable"]));
+    for (const resource of ["Dashboard", "Datasource", "DashboardProvider"]) expect(names).not.toContain(resource);
+    expect(names).toHaveLength(BUILTIN_CATALOG.filter((e) => e.entityKind === "property").length);
+  });
+
+  it("passes COR001, COR004 and COR009 on a dashboard written inline in one file", async () => {
+    const project = mkdtempSync(join(tmpdir(), "chant-grafana-lint-"));
+    try {
+      writeFileSync(join(project, "chant.config.json"), JSON.stringify({ lexicons: ["grafana"] }));
+      mkdirSync(join(project, "src"));
+      copyFileSync(join(fixture, "dashboard.ts"), join(project, "src", "dashboard.ts"));
+      const result = await lintCommand({ path: join(project, "src"), format: "stylish" });
+      expect(result.output).not.toMatch(/COR00[149]|LEX001/);
+      expect(result.warningCount).toBe(0);
+      expect(result.errorCount).toBe(0);
+    } finally {
+      rmSync(project, { recursive: true, force: true });
+    }
+  });
+
+  it("and that file builds", async () => {
+    const result = await build(fixture, [grafanaSerializer]);
+    expect(result.errors).toEqual([]);
+  });
+});

package/src/lint/post-synth/graf101.ts

@@ -1,7 +1,7 @@
 /**
- * GRAF101: A panel, query or variable uses a datasource no Datasource in the build declares
+ * GRAF101: A panel, query or variable uses a datasource no Datasource or ExternalDatasource in the build declares
  *
- * Grafana shows "datasource not found" on the panel. Typed references cannot go wrong this way, so it mostly catches a { type, uid } ref or a hand-edited dashboard. A panel with queries and no datasource at all is a warning: Grafana sends them to its default datasource. This check joins dashboards against the Datasource declarations of the same build root, so it goes silent across build roots (chant #1939): with no Datasource declared in the build it reports nothing, and a datasource declared in another build root looks undeclared. Keep datasources and the dashboards that use them in one build root.
+ * Grafana shows "datasource not found" on the panel. Typed references cannot go wrong this way, so it mostly catches a { type, uid } ref or a hand-edited dashboard. A datasource variable whose plugin type no declared datasource has is an error too. A panel with queries and no datasource at all is a warning: Grafana sends them to its default datasource. This check joins dashboards against the datasources of the same build root (chant #1939): declare one that exists in Grafana but is provisioned elsewhere with ExternalDatasource, which the check counts and the build never provisions. A build that declares no datasource at all gets one warning per dashboard that references any, since nothing can be checked.
  */
 
 import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
@@ -9,7 +9,7 @@ import { grafanaDiagnostics } from "./grafana-helpers";
 
 export const graf101: PostSynthCheck = {
   id: "GRAF101",
-  description: "A panel, query or variable uses a datasource no Datasource in the build declares",
+  description: "A panel, query or variable uses a datasource no Datasource or ExternalDatasource in the build declares",
 
   check(ctx: PostSynthContext): PostSynthDiagnostic[] {
     return grafanaDiagnostics(ctx, "GRAF101");

package/src/lint/post-synth/graf102.ts

@@ -1,7 +1,7 @@
 /**
  * GRAF102: A query is sent to a datasource of another plugin type
  *
- * A PromQL query sent to Tempo fails at query time. The typed classes prevent this at compile time; the check catches refs, datasource variables of the wrong plugin type and hand-edited dashboards. Like GRAF101 it joins against the Datasource declarations of the same build root and goes silent across build roots (chant #1939).
+ * A PromQL query sent to Tempo fails at query time. The typed classes prevent this at compile time; the check catches refs, datasource variables of the wrong plugin type and hand-edited dashboards. Like GRAF101 it joins against the Datasource and ExternalDatasource declarations of the same build root (chant #1939).
  */
 
 import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";

package/src/lint/post-synth/graf107.ts

@@ -1,7 +1,7 @@
 /**
  * GRAF107: A dashboard does not match the pinned Grafana schema
  *
- * The dashboard is validated against the dashboard schema at GRAFANA_SCHEMA_PIN, and each panel's options, fieldConfig.defaults.custom and queries against their plugin's schema with required fields relaxed (Grafana fills those in). What fails is a key the schema does not have or a value it does not allow: the edits Grafana would otherwise need on import.
+ * The dashboard is validated against the dashboard schema at GRAFANA_SCHEMA_PIN, with the correction overlay in src/spec/overlay/ applied, and each panel's options, fieldConfig.defaults.custom and queries against their plugin's schema with required fields relaxed (Grafana fills those in). Library panel models embedded in an export's __elements are checked the same way. A value the schema does not allow is an error: the edits Grafana would otherwise need on import. A key the schema does not know is a warning, since newer Grafana versions add keys before the pin catches up.
  */
 
 import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";

package/src/lint/post-synth/graf108.ts

@@ -0,0 +1,17 @@
+/**
+ * GRAF108: A query sent to Prometheus is not valid PromQL
+ *
+ * Each panel query, query variable and alert rule query whose datasource resolves to a prometheus datasource is parsed with the prometheus lexicon's checkPromql (@prometheus-io/lezer-promql), after its template variables ($var, ${var}, [[var]], $__interval, $__rate_interval, $__range and the other $__ macros) are replaced with placeholders that parse where they stand. A query whose datasource can't be told is not parsed; an alert rule query is parsed when its datasourceUid is a declared prometheus datasource or its model says `datasource.type: prometheus`. It is a syntax check: an unbalanced bracket or a bad duration fails, rate over an instant vector does not.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { grafanaDiagnostics } from "./grafana-helpers";
+
+export const graf108: PostSynthCheck = {
+  id: "GRAF108",
+  description: "A query sent to Prometheus is not valid PromQL",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return grafanaDiagnostics(ctx, "GRAF108");
+  },
+};

package/src/lint/post-synth/graf109.ts

@@ -0,0 +1,17 @@
+/**
+ * GRAF109: Dashboard provisioning puts a dashboard somewhere other than its declared folder, or loads it twice
+ *
+ * Read from the dashboard provisioning file and where each dashboard file sits under dashboards/. Two providers in one org whose paths are the same or nested load every dashboard twice, and Grafana then takes database writes away from both: an error. A provider that sets folder and folderUid with foldersFromFilesStructure is refused by Grafana: an error; with one of them, that folder is ignored: a warning. Dashboards that declare a folder when no provider sets foldersFromFilesStructure all land in the provider's folder: a warning. A nested folder ("Platform/Kubernetes") is a warning: Grafana 13.1 and later nest the folders, 12.4 and 13.0 use only the last level; past Grafana's default depth of 4 it says so, and past its hard limit of 7 it is an error.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { grafanaDiagnostics } from "./grafana-helpers";
+
+export const graf109: PostSynthCheck = {
+  id: "GRAF109",
+  description: "Dashboard provisioning puts a dashboard somewhere other than its declared folder, or loads it twice",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return grafanaDiagnostics(ctx, "GRAF109");
+  },
+};

package/src/lint/post-synth/graf111.ts

@@ -0,0 +1,17 @@
+/**
+ * GRAF111: An alert rule's condition, expression inputs or refIds do not fit together
+ *
+ * Each alert rule's condition, each server-side expression's inputs (a reduce, threshold or resample `expression`, the `$A` references of a math expression, a classic condition's query) and a recording rule's record.from must name a refId of the same rule; refIds must be unique, and a rule needs a condition unless it records. Each expression model is also validated against the pinned `expr` schema (a missing reducer, an unknown evaluator type). Grafana refuses such a rule, and a refused rule stops it provisioning every alerting file at startup.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { grafanaDiagnostics } from "./grafana-helpers";
+
+export const graf111: PostSynthCheck = {
+  id: "GRAF111",
+  description: "An alert rule's condition, expression inputs or refIds do not fit together",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return grafanaDiagnostics(ctx, "GRAF111");
+  },
+};

package/src/lint/post-synth/graf112.ts

@@ -0,0 +1,17 @@
+/**
+ * GRAF112: An alert rule queries a datasource the build does not declare, or of another type
+ *
+ * Each alert rule query's datasourceUid must be a datasource the build declares: a Datasource it provisions or an ExternalDatasource that already exists in Grafana. A query whose model states a datasource type (model.datasource.type) must match the declared type, and a recording rule's targetDatasourceUid must be a declared Prometheus datasource. With no datasource declared at all, it warns once that it cannot check.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { grafanaDiagnostics } from "./grafana-helpers";
+
+export const graf112: PostSynthCheck = {
+  id: "GRAF112",
+  description: "An alert rule queries a datasource the build does not declare, or of another type",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return grafanaDiagnostics(ctx, "GRAF112");
+  },
+};

package/src/lint/post-synth/graf113.ts

@@ -0,0 +1,17 @@
+/**
+ * GRAF113: Alerting routes to a contact point or mute timing the build does not declare, or a policy matcher does not parse
+ *
+ * The notification policy tree's receivers, every rule's notification_settings.receiver, and each mute_time_intervals and active_time_intervals entry must name a ContactPoint or MuteTiming the build declares (grafana-default-email exists in every Grafana). Policy object_matchers must be [label, op, value] with op =, !=, =~ or !~ and a valid regex; matchers must parse as Alertmanager matchers. With no contact point or mute timing declared it warns once that it cannot check.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { grafanaDiagnostics } from "./grafana-helpers";
+
+export const graf113: PostSynthCheck = {
+  id: "GRAF113",
+  description: "Alerting routes to a contact point or mute timing the build does not declare, or a policy matcher does not parse",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return grafanaDiagnostics(ctx, "GRAF113");
+  },
+};

package/src/lint/post-synth/graf114.ts

@@ -0,0 +1,17 @@
+/**
+ * GRAF114: An alerting uid, name, title or interval Grafana rejects, or one declared twice
+ *
+ * Rule uids and contact point receiver uids must be 1-40 letters, digits, - and _; rules need a title of at most 190 characters; groups need a name, a folder and an interval that is a positive multiple of 10s; for and keepFiringFor must be durations; noDataState and execErrState must be values Grafana knows. Rule uids, group names within a folder, contact point names, receiver uids, mute timing and template names must be unique per organisation, and each organisation has one policy tree. Grafana refuses the file otherwise, and one refused file stops it provisioning every alerting file.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { grafanaDiagnostics } from "./grafana-helpers";
+
+export const graf114: PostSynthCheck = {
+  id: "GRAF114",
+  description: "An alerting uid, name, title or interval Grafana rejects, or one declared twice",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return grafanaDiagnostics(ctx, "GRAF114");
+  },
+};

package/src/lint/post-synth/graf115.ts

@@ -0,0 +1,17 @@
+/**
+ * GRAF115: A unit Grafana doesn't know
+ *
+ * Each panel's `fieldConfig.defaults.unit`, every `unit` override, a heatmap's `options.yAxis.unit` and `options.cellValues.unit`, and a legacy graph panel's `yaxes[].format` are looked up in Grafana's unit registry at v13.2.2 (`src/spec/units.gen.ts`). Custom units (`prefix:`, `suffix:`, `time:`, `si:`, `count:`, `currency:`, `bool:`) pass. Anything else Grafana shows as a literal suffix, so it is a warning that names the closest registered id.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { grafanaDiagnostics } from "./grafana-helpers";
+
+export const graf115: PostSynthCheck = {
+  id: "GRAF115",
+  description: "A panel unit Grafana doesn't know, which it shows as a literal suffix",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return grafanaDiagnostics(ctx, "GRAF115");
+  },
+};

package/src/lint/post-synth/grafana-helpers.ts

@@ -1,18 +1,21 @@
 /**
- * Shared plumbing for the grafana post-synth checks: find the dashboards and
- * provisioned datasources in a build's output, and run the plain-function
- * checks in `validate-output.ts` over them.
+ * Shared plumbing for the grafana post-synth checks: find the dashboards,
+ * provisioned datasources, dashboard providers and alerting provisioning
+ * files in a build's output, and run the plain-function checks in
+ * `validate-output.ts` over them.
  *
  * Any output file shaped like a dashboard or a datasource provisioning file
  * counts, not only the grafana lexicon's own, so a dashboard another lexicon
- * embeds is checked the same way.
+ * embeds is checked the same way. `ExternalDatasource` declarations are never
+ * written to a provisioning file, so they come from the build's entities.
  */
 
 import type { PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
 import type { SerializerResult } from "@intentius/chant/serializer";
 import { loadAll } from "js-yaml";
-import { looksLikeDashboard, looksLikeDatasourceProvisioning } from "../../detect";
-import type { ProvisionedDatasource } from "../../build";
+import { looksLikeAlertingProvisioning, looksLikeDashboard, looksLikeDashboardProvisioning, looksLikeDatasourceProvisioning } from "../../detect";
+import { externalDatasourceRecord, type ProvisionedDatasource } from "../../build";
+import { isExternalDatasource } from "../../datasource";
 import { issuesFor, type GrafanaArtifacts, type GrafanaIssueCode } from "../../validate-output";
 
 function parse(text: string, name: string): unknown[] {
@@ -30,9 +33,10 @@ function parse(text: string, name: string): unknown[] {
   }
 }
 
-/** Every dashboard and provisioned datasource in the build's output. */
+/** Every dashboard, provisioned datasource and dashboard provider and alerting provisioning file in the build's output, and every `ExternalDatasource` it declares. */
 export function grafanaArtifacts(ctx: PostSynthContext): GrafanaArtifacts {
-  const out: GrafanaArtifacts = { dashboards: [], datasources: [] };
+  const externalDatasources = [...(ctx.entities?.values() ?? [])].filter(isExternalDatasource).map(externalDatasourceRecord);
+  const out: GrafanaArtifacts = { dashboards: [], datasources: [], externalDatasources, providers: [], alerting: [] };
   for (const [lexicon, output] of ctx.outputs) {
     const texts: Array<[string, string]> =
       typeof output === "string"
@@ -42,6 +46,9 @@ export function grafanaArtifacts(ctx: PostSynthContext): GrafanaArtifacts {
       if (!text) continue;
       for (const doc of parse(text, source)) {
         if (looksLikeDashboard(doc)) out.dashboards.push({ source, json: doc });
+        else if (looksLikeDashboardProvisioning(doc)) {
+          for (const p of doc.providers) if (p && typeof p === "object" && !Array.isArray(p)) out.providers!.push(p as Record<string, unknown>);
+        } else if (looksLikeAlertingProvisioning(doc)) out.alerting!.push({ source, json: doc });
         else if (looksLikeDatasourceProvisioning(doc)) {
           for (const d of doc.datasources) {
             if (d && typeof d === "object" && typeof (d as ProvisionedDatasource).name === "string") {

package/src/lint/post-synth/index.ts

@@ -7,6 +7,13 @@ import { graf104 } from "./graf104";
 import { graf105 } from "./graf105";
 import { graf106 } from "./graf106";
 import { graf107 } from "./graf107";
+import { graf108 } from "./graf108";
+import { graf109 } from "./graf109";
+import { graf111 } from "./graf111";
+import { graf112 } from "./graf112";
+import { graf113 } from "./graf113";
+import { graf114 } from "./graf114";
+import { graf115 } from "./graf115";
 
 export const postSynthChecks: PostSynthCheck[] = [
   graf101,
@@ -16,4 +23,11 @@ export const postSynthChecks: PostSynthCheck[] = [
   graf105,
   graf106,
   graf107,
+  graf108,
+  graf109,
+  graf111,
+  graf112,
+  graf113,
+  graf114,
+  graf115,
 ];