@intentius/chant-lexicon-grafana 0.97.0 → 0.99.0

package/src/schema-overlay.test.ts

@@ -0,0 +1,282 @@
+/**
+ * The correction overlay (chant #2939, #2971): real Grafana 12.4 and 13.x
+ * exports pass GRAF107, the reproductions from the issues type and build,
+ * unknown keys are warnings, genuine type violations stay errors, and the
+ * library panels an external export embeds in `__elements` are checked.
+ */
+import { describe, expect, test } from "vitest";
+import { readdirSync, readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { SCHEMA_NAMES } from "./pin";
+import { applyOverlay, loadOverlay, type SchemaOverlay } from "./spec/overlay";
+import { loadSchema, loadVendoredSchema } from "./spec/schemas";
+import { validateDashboardSchema } from "./schema-validate";
+import { checkSchema } from "./validate-output";
+import { renderDashboard } from "./build";
+import { Dashboard } from "./dashboard";
+import { TablePanel, TimeSeriesPanel } from "./panels";
+import { PromQuery } from "./query";
+import { Datasource } from "./datasource";
+
+const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+const exportsDir = join(pkgDir, "test", "fixtures", "exports");
+
+type Json = Record<string, unknown>;
+
+function readJson(path: string): Json {
+  return JSON.parse(readFileSync(path, "utf-8")) as Json;
+}
+
+const versions = readdirSync(exportsDir).filter((d) => d.startsWith("grafana-"));
+const classicExports = versions.flatMap((v) =>
+  readdirSync(join(exportsDir, v))
+    // The v1 and v2 resources (#2947) are API reads, not classic exports.
+    .filter((f) => f.endsWith(".json") && !f.includes("-resource"))
+    .map((f) => [`${v}/${f}`, join(exportsDir, v, f)] as const),
+);
+
+describe("the overlay files", () => {
+  test("every patch cites its Grafana source and says why", () => {
+    for (const name of SCHEMA_NAMES) {
+      const overlay = loadOverlay(name);
+      if (!overlay) continue;
+      expect(overlay.grafana).toMatch(/^v\d+\.\d+\.\d+$/);
+      for (const p of overlay.patches) {
+        expect({ path: p.path, source: p.source }).toEqual({ path: p.path, source: expect.stringMatching(/\.(cue|ts|go):\d+/) });
+        expect(p.why.length).toBeGreaterThan(0);
+      }
+    }
+  });
+
+  test("the schemas with an overlay are patched; the vendored bytes are not", () => {
+    expect(SCHEMA_NAMES.filter((n) => loadOverlay(n))).toEqual(["dashboard", "timeseries", "table", "logs", "piechart", "nodegraph", "xychart", "trend", "canvas", "geomap", "expr"]);
+    const vendored = loadVendoredSchema("dashboard").definitions as Record<string, Json>;
+    const patched = loadSchema("dashboard").definitions as Record<string, Json>;
+    expect((vendored.MatcherConfig.properties as Json).scope).toBeUndefined();
+    expect((patched.MatcherConfig.properties as Json).scope).toEqual(expect.objectContaining({ $ref: "#/definitions/MatcherScope" }));
+  });
+
+  test("applying refuses a patch the vendored schema already carries, or a path it lacks", () => {
+    const base = { definitions: { A: { properties: { x: { type: "string" } } } } };
+    const overlay = (patches: SchemaOverlay["patches"]): SchemaOverlay => ({ schema: "dashboard", grafana: "v13.2.2", patches });
+    const cite = { source: "kinds/dashboard/dashboard_kind.cue:1", why: "test" };
+    expect(() => applyOverlay(base, overlay([{ op: "add", path: "/definitions/A/properties/x", value: {}, ...cite }]))).toThrow(/already present/);
+    expect(() => applyOverlay(base, overlay([{ op: "replace", path: "/definitions/A/properties/y", value: {}, ...cite }]))).toThrow(/not present/);
+    expect(() => applyOverlay(base, overlay([{ op: "remove", path: "/definitions/B/properties", ...cite }]))).toThrow(/no parent/);
+    const out = applyOverlay(base, overlay([{ op: "add", path: "/definitions/A/properties/y", value: { type: "number" }, ...cite }]));
+    expect(out).toEqual({ definitions: { A: { properties: { x: { type: "string" }, y: { type: "number" } } } } });
+    expect(base.definitions.A.properties).toEqual({ x: { type: "string" } });
+  });
+});
+
+describe("real Grafana exports", () => {
+  test("the corpus covers Grafana 12.4 and 13.2, plain and shared externally", () => {
+    expect(versions).toEqual(["grafana-12.4.11", "grafana-13.2.2"]);
+    expect(classicExports.map(([name]) => name)).toEqual(
+      expect.arrayContaining([
+        "grafana-12.4.11/checkout.external.json",
+        "grafana-13.2.2/slo.external.json",
+        "grafana-13.2.2/checkout.json",
+        "grafana-13.2.2/cells.external.json",
+      ]),
+    );
+  });
+
+  test.each(classicExports)("%s passes GRAF107 with no errors or warnings", (name, path) => {
+    const json = readJson(path);
+    expect({ name, problems: validateDashboardSchema(json) }).toEqual({ name, problems: [] });
+    expect(checkSchema({ dashboards: [{ source: name, json }], datasources: [] })).toEqual([]);
+  });
+
+  test("the external exports carry the metadata the overlay allows", () => {
+    const json = readJson(join(exportsDir, "grafana-13.2.2", "slo.external.json"));
+    expect(Object.keys(json)).toEqual(expect.arrayContaining(["__inputs", "__requires", "__elements"]));
+    expect(Object.keys(json.__elements as Json)).toEqual(["chant-fx-burn"]);
+  });
+});
+
+describe("enum values newer than the pin", () => {
+  const cells = readJson(join(exportsDir, "grafana-13.2.2", "cells.external.json"));
+  const panels = (cells.panels as Json[]).filter((p) => !p.libraryPanel);
+  const custom = (p: Json) => ((p.fieldConfig as Json).defaults as Json).custom as Json;
+  const colorMode = (p: Json) => (((p.fieldConfig as Json).defaults as Json).color as Json).mode;
+
+  test("the 13.2 cells export uses them, in panels and in its library panel", () => {
+    expect(panels.map((p) => (custom(p)?.cellOptions as Json | undefined)?.type).filter(Boolean)).toEqual(["pill", "markdown", "geo"]);
+    expect(panels.map(colorMode)).toEqual([
+      "continuous-viridis",
+      "continuous-magma",
+      "continuous-plasma",
+      "continuous-inferno",
+    ]);
+    expect(custom(panels[3]).lineStyle).toEqual({ fill: "accessible" });
+    const model = ((cells.__elements as Json)["chant-fx-owners"] as Json).model as Json;
+    expect([(custom(model).cellOptions as Json).type, colorMode(model)]).toEqual(["markdown", "continuous-cividis"]);
+  });
+
+  test("the vendored schemas reject them; the overlay accepts them", () => {
+    const enumOf = (schema: Json, def: string) => ((schema.definitions as Json)[def] as Json).enum as string[];
+    const fill = (schema: Json) => ((((schema.definitions as Json).LineStyle as Json).properties as Json).fill as Json).enum as string[];
+    for (const [name, def, value] of [
+      ["dashboard", "FieldColorModeId", "continuous-viridis"],
+      ["table", "TableCellDisplayMode", "pill"],
+      ["table", "TableCellDisplayMode", "markdown"],
+      ["table", "TableCellDisplayMode", "geo"],
+    ] as const) {
+      expect(enumOf(loadVendoredSchema(name), def)).not.toContain(value);
+      expect(enumOf(loadSchema(name), def)).toContain(value);
+    }
+    for (const name of ["timeseries", "table"] as const) {
+      expect(fill(loadVendoredSchema(name))).not.toContain("accessible");
+      expect(fill(loadSchema(name))).toContain("accessible");
+    }
+  });
+
+  test("an unknown enum value is still an error", () => {
+    const bad = structuredClone(cells);
+    custom((bad.panels as Json[])[0]).cellOptions = { type: "hologram" };
+    const problems = validateDashboardSchema(bad);
+    expect(problems.map((p) => [p.severity, p.path])).toContainEqual(["error", "/panels/0/fieldConfig/defaults/custom/cellOptions/type"]);
+  });
+});
+
+describe("library panels in __elements", () => {
+  const external = () => readJson(join(exportsDir, "grafana-13.2.2", "slo.external.json"));
+  const burn = (json: Json) => ((json.__elements as Json)["chant-fx-burn"] as Json).model as Json;
+
+  test("a bad library panel model is reported at its path", () => {
+    const json = external();
+    const model = burn(json);
+    ((model.options as Json).legend as Json).displayMode = "sideways";
+    (model.targets as Json[])[0].format = "csv";
+    model.transparent = "yes";
+    model.fancyNewField = true;
+    const problems = validateDashboardSchema(json).map((p) => `${p.severity} ${p.path}: ${p.message}`);
+    expect(problems).toEqual(
+      expect.arrayContaining([
+        expect.stringMatching(/^error \/__elements\/chant-fx-burn\/model\/options\/legend\/displayMode: must be equal to one of the allowed values/),
+        expect.stringMatching(/^error \/__elements\/chant-fx-burn\/model\/targets\/0\/format: must be equal to one of the allowed values/),
+        "error /__elements/chant-fx-burn/model/transparent: must be boolean",
+        'warning /__elements/chant-fx-burn/model: unknown key "fancyNewField" (not in the pinned schema)',
+      ]),
+    );
+    expect(problems).toHaveLength(4);
+    const issues = checkSchema({ dashboards: [{ source: "slo.external.json", json }], datasources: [] });
+    expect(issues.filter((i) => i.code === "GRAF107" && i.severity === "error")).toHaveLength(3);
+  });
+
+  test("a model with neither a type nor a library panel reference is an error", () => {
+    const json = external();
+    delete burn(json).type;
+    expect(validateDashboardSchema(json).map((p) => [p.severity, p.path, p.message])).toEqual([
+      ["error", "/__elements/chant-fx-burn/model", "must have required property 'type'"],
+      ["error", "/__elements/chant-fx-burn/model", "must have required property 'libraryPanel'"],
+    ]);
+  });
+
+  test("the element itself is checked by the envelope, and a uid with a slash is escaped in the path", () => {
+    const json = external();
+    const el = (json.__elements as Json)["chant-fx-burn"] as Json;
+    json.__elements = { "team/burn": { ...el, uid: "team/burn", name: 7, model: { ...(el.model as Json), title: 9 } } };
+    expect(validateDashboardSchema(json).map((p) => `${p.path}: ${p.message}`)).toEqual([
+      "/__elements/team~1burn/name: must be string",
+      "/__elements/team~1burn/model/title: must be string",
+    ]);
+  });
+
+  test("an element of another kind is not read as a panel", () => {
+    const json = external();
+    const el = (json.__elements as Json)["chant-fx-burn"] as Json;
+    json.__elements = { "chant-fx-burn": { ...el, kind: 2, model: { type: 7 } } };
+    expect(validateDashboardSchema(json)).toEqual([]);
+  });
+});
+
+describe("the issue's reproductions", () => {
+  const prometheus = new Datasource({ name: "Prometheus", type: "prometheus" });
+  const rate = new PromQuery({ expr: "sum(rate(http_requests_total[5m]))" });
+
+  test("a byName matcher with a string option and a data link with only title and url type, build and pass", () => {
+    const panel = new TimeSeriesPanel({
+      title: "Requests",
+      datasource: prometheus,
+      targets: [rate],
+      fieldConfig: {
+        defaults: { links: [{ title: "Runbook", url: "https://example.com/runbook" }] },
+        overrides: [
+          { matcher: { id: "byName", options: "requests" }, properties: [{ id: "unit", value: "reqps" }] },
+          { matcher: { id: "byType", options: "number", scope: "series" }, properties: [{ id: "decimals", value: 1 }] },
+        ],
+      },
+      links: [{ title: "Traces", url: "https://example.com/traces", targetBlank: true }],
+    });
+    const json = renderDashboard(new Dashboard({ title: "Repro", uid: "repro", panels: [panel] })) as unknown as Json;
+    expect(validateDashboardSchema(json)).toEqual([]);
+  });
+
+  test("a table cellOptions matching several variants is accepted", () => {
+    const panel = new TablePanel({ title: "T", fieldConfig: { defaults: { custom: { cellOptions: { type: "auto" } } } } });
+    const json = renderDashboard(new Dashboard({ title: "Table", uid: "table", panels: [panel] })) as unknown as Json;
+    expect(validateDashboardSchema(json)).toEqual([]);
+  });
+});
+
+describe("errors and warnings", () => {
+  function dashboard(extra: Json = {}, panel: Json = {}): Json {
+    return {
+      uid: "d",
+      title: "D",
+      schemaVersion: 42,
+      panels: [{ type: "timeseries", id: 1, gridPos: { x: 0, y: 0, w: 12, h: 8 }, fieldConfig: { defaults: {}, overrides: [] }, ...panel }],
+      ...extra,
+    };
+  }
+
+  test("a key the pin does not know is a warning, wherever it is", () => {
+    const problems = validateDashboardSchema(
+      dashboard({ fancyNewField: true }, { fieldConfig: { defaults: { custom: { brandNewOption: 1 } }, overrides: [] } }),
+    );
+    expect(problems).toEqual([
+      { path: "/", message: 'unknown key "fancyNewField" (not in the pinned schema)', severity: "warning" },
+      { path: "/panels/0/fieldConfig/defaults/custom", message: 'unknown key "brandNewOption" (not in the pinned schema)', severity: "warning" },
+    ]);
+  });
+
+  test("a genuine type violation stays an error", () => {
+    const problems = validateDashboardSchema(
+      dashboard(
+        { templating: { list: [{ type: "query", name: "q", query: 5 }] } },
+        { fieldConfig: { defaults: {}, overrides: [{ matcher: { id: 7, scope: "everything" }, properties: [] }] }, links: [{ url: "x" }] },
+      ),
+    );
+    expect(problems.filter((p) => p.severity === "error").map((p) => `${p.path}: ${p.message}`)).toEqual(
+      expect.arrayContaining([
+        "/templating/list/0/query: must be string",
+        "/templating/list/0/query: must be object",
+        "/panels/0/links/0: must have required property 'title'",
+        "/panels/0/fieldConfig/overrides/0/matcher/id: must be string",
+        expect.stringMatching(/^\/panels\/0\/fieldConfig\/overrides\/0\/matcher\/scope: must be equal to one of the allowed values/),
+      ]),
+    );
+    expect(problems.every((p) => p.severity === "error")).toBe(true);
+  });
+
+  test("a panel with neither a type nor a library panel is an error; a library panel reference is fine", () => {
+    const bare = validateDashboardSchema({ uid: "d", title: "D", schemaVersion: 42, panels: [{ id: 1, gridPos: { x: 0, y: 0, w: 6, h: 6 } }] });
+    expect(bare.map((p) => [p.severity, p.message])).toEqual([
+      ["error", "must have required property 'type'"],
+      ["error", "must have required property 'libraryPanel'"],
+    ]);
+    const lib = { id: 1, gridPos: { x: 0, y: 0, w: 6, h: 6 }, libraryPanel: { uid: "u", name: "n" } };
+    expect(validateDashboardSchema({ uid: "d", title: "D", schemaVersion: 42, panels: [lib] })).toEqual([]);
+  });
+
+  test("GRAF107 carries the severity through", () => {
+    const issues = checkSchema({ dashboards: [{ json: dashboard({ fancyNewField: true, graphTooltip: 7 }) }], datasources: [] });
+    expect(issues.map((i) => [i.code, i.severity])).toEqual([
+      ["GRAF107", "error"],
+      ["GRAF107", "warning"],
+    ]);
+  });
+});

package/src/schema-validate.ts

@@ -1,12 +1,29 @@
 /**
  * Validate built Grafana JSON against the vendored schemas at
- * `GRAFANA_SCHEMA_PIN`, offline.
+ * `GRAFANA_SCHEMA_PIN`, with the correction overlay applied, offline.
  *
  * The dashboard is checked against the dashboard schema as it stands. Panel
  * options, `fieldConfig.defaults.custom` and each query are checked against
  * their plugin's schema with every `required` list removed, because Grafana
- * fills in options a panel leaves out: what still fails is a key the schema
- * doesn't have or a value it doesn't allow.
+ * fills in options a panel leaves out.
+ *
+ * Two kinds of problem come back. A value the schema does not allow (a
+ * wrong type, an enum value it does not list, a required field missing) is
+ * an error. A key the pinned schema does not know is a warning: Grafana
+ * adds fields every minor release and keeps what it does not understand, so
+ * an unknown key is more often a newer Grafana than a mistake. To tell the
+ * two apart each value is validated twice, once with every object opened
+ * (`additionalProperties: false` dropped; what fails is an error) and once
+ * as pinned (what fails only for an unknown key is a warning).
+ *
+ * An export shared externally embeds its library panels in `__elements`;
+ * each element's `model` is checked the same way as a panel on the grid.
+ *
+ * `oneOf` is read as `anyOf` throughout. The CUE these schemas come from
+ * has disjunctions, which accept a value matching any branch; cog writes
+ * them as `oneOf`, which rejects a value matching two, and loosely
+ * discriminated unions (a table's `cellOptions: { type: "auto" }` matches
+ * several variants) match more than one.
  */
 
 import Ajv, { type ValidateFunction, type ErrorObject } from "ajv";
@@ -19,6 +36,8 @@ export interface SchemaProblem {
   /** JSON pointer into the dashboard. */
   path: string;
   message: string;
+  /** `error` for a value the schema does not allow, `warning` for a key it does not know. */
+  severity: "error" | "warning";
 }
 
 let ajv: Ajv | undefined;
@@ -29,22 +48,30 @@ function getAjv(): Ajv {
 
 const compiled = new Map<string, ValidateFunction>();
 
-function stripRequired(node: unknown): unknown {
-  if (Array.isArray(node)) return node.map(stripRequired);
+interface Mode {
+  /** Drop every `required` list (panel options and queries: Grafana fills them in). */
+  lenient: boolean;
+  /** Drop every `additionalProperties: false`, so unknown keys pass. */
+  open: boolean;
+}
+
+function prepare(node: unknown, mode: Mode): unknown {
+  if (Array.isArray(node)) return node.map((n) => prepare(n, mode));
   if (node && typeof node === "object") {
     const out: Record<string, unknown> = {};
     for (const [k, v] of Object.entries(node)) {
-      if (k === "required" && Array.isArray(v)) continue;
-      out[k] = stripRequired(v);
+      if (mode.lenient && k === "required" && Array.isArray(v)) continue;
+      if (mode.open && k === "additionalProperties" && v === false) continue;
+      out[k === "oneOf" && Array.isArray(v) ? "anyOf" : k] = prepare(v, mode);
     }
     return out;
   }
   return node;
 }
 
-/** A validator for one definition of one vendored schema (the root `$ref` when `def` is left out). */
-function validatorFor(name: SchemaName, def: string | undefined, lenient: boolean): ValidateFunction | undefined {
-  const key = `${name}#${def ?? ""}#${lenient}`;
+/** A validator for one definition of one schema (the root `$ref` when `def` is left out). */
+function validatorFor(name: SchemaName, def: string | undefined, mode: Mode): ValidateFunction | undefined {
+  const key = `${name}#${def ?? ""}#${mode.lenient}#${mode.open}`;
   const hit = compiled.get(key);
   if (hit) return hit;
   const schema = loadSchema(name);
@@ -55,31 +82,48 @@ function validatorFor(name: SchemaName, def: string | undefined, lenient: boolea
   const root: Record<string, unknown> = {
     $schema: schema.$schema,
     $ref: ref,
-    definitions: lenient ? stripRequired(definitions) : definitions,
+    definitions: prepare(definitions, mode),
   };
   const fn = getAjv().compile(root);
   compiled.set(key, fn);
   return fn;
 }
 
-function problems(errors: ErrorObject[] | null | undefined, prefix: string): SchemaProblem[] {
+function describe(e: ErrorObject): string {
+  const extra =
+    e.keyword === "enum" ? `: ${(e.params as { allowedValues: unknown[] }).allowedValues.map((v) => JSON.stringify(v)).join(", ")}` : "";
+  return `${e.message ?? "is invalid"}${extra}`;
+}
+
+/**
+ * Everything wrong with one value against one definition: errors from the
+ * opened schema, then unknown keys from the pinned one.
+ */
+function check(value: unknown, name: SchemaName, def: string | undefined, lenient: boolean, prefix: string): SchemaProblem[] {
+  const open = validatorFor(name, def, { lenient, open: true });
+  const closed = validatorFor(name, def, { lenient, open: false });
+  if (!open || !closed) return [];
   const seen = new Set<string>();
   const out: SchemaProblem[] = [];
-  for (const e of errors ?? []) {
-    // oneOf/anyOf wrappers repeat what their branches already said.
-    if (e.keyword === "oneOf" || e.keyword === "anyOf" || e.keyword === "if") continue;
-    const extra =
-      e.keyword === "additionalProperties"
-        ? ` ("${(e.params as { additionalProperty: string }).additionalProperty}")`
-        : e.keyword === "enum"
-          ? `: ${(e.params as { allowedValues: unknown[] }).allowedValues.map((v) => JSON.stringify(v)).join(", ")}`
-          : "";
-    const path = `${prefix}${e.instancePath}` || "/";
-    const message = `${e.message ?? "is invalid"}${extra}`;
+  const push = (path: string, message: string, severity: SchemaProblem["severity"]) => {
     const k = `${path} ${message}`;
-    if (seen.has(k)) continue;
+    if (seen.has(k)) return;
     seen.add(k);
-    out.push({ path, message });
+    out.push({ path, message, severity });
+  };
+  if (!open(value)) {
+    for (const e of open.errors ?? []) {
+      // anyOf/if wrappers repeat what their branches already said.
+      if (e.keyword === "oneOf" || e.keyword === "anyOf" || e.keyword === "if") continue;
+      push(`${prefix}${e.instancePath}` || "/", describe(e), "error");
+    }
+  }
+  if (!closed(value)) {
+    for (const e of closed.errors ?? []) {
+      if (e.keyword !== "additionalProperties") continue;
+      const key = (e.params as { additionalProperty: string }).additionalProperty;
+      push(`${prefix}${e.instancePath}` || "/", `unknown key "${key}" (not in the pinned schema)`, "warning");
+    }
   }
   return out;
 }
@@ -98,46 +142,93 @@ function panelsOf(dashboard: Json): Array<{ panel: Json; path: string }> {
   return out;
 }
 
-/** Everything in one dashboard that the pinned schemas reject. */
+/** A panel (not a row) against the dashboard's Panel definition and its plugin's options, custom field config and queries. */
+function checkPanel(panel: Json, path: string): SchemaProblem[] {
+  const out = check(panel, "dashboard", "Panel", false, path);
+  const def = typeof panel.type === "string" ? panelDefinitionFor(panel.type) : undefined;
+  if (def?.schema) {
+    if (panel.options !== undefined) out.push(...check(panel.options, def.schema, "Options", true, `${path}/options`));
+    const custom = (panel.fieldConfig as { defaults?: { custom?: unknown } } | undefined)?.defaults?.custom;
+    if (custom !== undefined) out.push(...check(custom, def.schema, "FieldConfig", true, `${path}/fieldConfig/defaults/custom`));
+  }
+  const panelType = (panel.datasource as { type?: string } | undefined)?.type;
+  const targets = Array.isArray(panel.targets) ? (panel.targets as Json[]) : [];
+  targets.forEach((t, k) => {
+    const type = (t?.datasource as { type?: string } | undefined)?.type ?? panelType;
+    const qdef = type ? queryDefinitionFor(type) : undefined;
+    if (!qdef?.schema) return;
+    out.push(...check(t, qdef.schema, undefined, true, `${path}/targets/${k}`));
+  });
+  return out;
+}
+
+/** `LibraryElementKind.Panel` (public/app/features/library-panels/types.ts:8-10 at v13.2.2, its only member). */
+const LIBRARY_PANEL_KIND = 1;
+
+/**
+ * The library panel models an external export embeds in `__elements`. The
+ * envelope check covers each element's own fields (uid, name, kind, model
+ * present); the model is a whole panel, checked like one.
+ */
+function libraryPanelModels(dashboard: Json): Array<{ panel: Json; path: string }> {
+  const elements = dashboard.__elements;
+  if (!elements || typeof elements !== "object" || Array.isArray(elements)) return [];
+  const out: Array<{ panel: Json; path: string }> = [];
+  for (const [key, el] of Object.entries(elements as Record<string, unknown>)) {
+    if (!el || typeof el !== "object") continue;
+    const { kind, model } = el as { kind?: unknown; model?: unknown };
+    if (kind !== undefined && kind !== LIBRARY_PANEL_KIND) continue;
+    if (!model || typeof model !== "object" || Array.isArray(model)) continue;
+    out.push({ panel: model as Json, path: `/__elements/${key.replace(/~/g, "~0").replace(/\//g, "~1")}/model` });
+  }
+  return out;
+}
+
+/** Everything in one dashboard that the pinned schemas reject or do not know. */
 export function validateDashboardSchema(dashboard: Json): SchemaProblem[] {
   const out: SchemaProblem[] = [];
   // The envelope and each panel are checked separately: the schema's
   // `oneOf [Panel, RowPanel]` would otherwise report every panel error twice,
   // once per branch.
-  const whole = validatorFor("dashboard", undefined, false)!;
   const envelope = Array.isArray(dashboard.panels) ? { ...dashboard, panels: [] } : dashboard;
-  if (!whole(envelope)) out.push(...problems(whole.errors, ""));
-  const panelSchema = validatorFor("dashboard", "Panel", false)!;
-  const rowSchema = validatorFor("dashboard", "RowPanel", false)!;
+  out.push(...check(envelope, "dashboard", undefined, false, ""));
 
   for (const { panel, path } of panelsOf(dashboard)) {
     if (!panel || typeof panel !== "object") {
-      out.push({ path, message: "must be object" });
+      out.push({ path, message: "must be object", severity: "error" });
       continue;
     }
     if (panel.type === "row") {
       const header = Array.isArray(panel.panels) ? { ...panel, panels: [] } : panel;
-      if (!rowSchema(header)) out.push(...problems(rowSchema.errors, path));
+      out.push(...check(header, "dashboard", "RowPanel", false, path));
       continue;
     }
-    if (!panelSchema(panel)) out.push(...problems(panelSchema.errors, path));
-    const def = typeof panel.type === "string" ? panelDefinitionFor(panel.type) : undefined;
-    if (def?.schema) {
-      const options = validatorFor(def.schema, "Options", true);
-      if (options && panel.options !== undefined && !options(panel.options)) out.push(...problems(options.errors, `${path}/options`));
-      const custom = (panel.fieldConfig as { defaults?: { custom?: unknown } } | undefined)?.defaults?.custom;
-      const fc = validatorFor(def.schema, "FieldConfig", true);
-      if (fc && custom !== undefined && !fc(custom)) out.push(...problems(fc.errors, `${path}/fieldConfig/defaults/custom`));
-    }
-    const panelType = (panel.datasource as { type?: string } | undefined)?.type;
-    const targets = Array.isArray(panel.targets) ? (panel.targets as Json[]) : [];
-    targets.forEach((t, k) => {
-      const type = (t?.datasource as { type?: string } | undefined)?.type ?? panelType;
-      const qdef = type ? queryDefinitionFor(type) : undefined;
-      if (!qdef?.schema) return;
-      const v = validatorFor(qdef.schema, undefined, true);
-      if (v && !v(t)) out.push(...problems(v.errors, `${path}/targets/${k}`));
-    });
+    out.push(...checkPanel(panel, path));
   }
+  for (const { panel, path } of libraryPanelModels(dashboard)) out.push(...checkPanel(panel, path));
   return out;
 }
+
+/** The `expr` schema definition for each server-side expression type. */
+const EXPRESSION_DEFINITIONS: Record<string, string> = {
+  math: "TypeMath",
+  reduce: "TypeReduce",
+  resample: "TypeResample",
+  classic_conditions: "TypeClassicConditions",
+  threshold: "TypeThreshold",
+  sql: "TypeSql",
+};
+
+/**
+ * Check one server-side expression model (an alert rule's `data[].model`
+ * whose datasource is `__expr__`) against the pinned `expr` schema, as
+ * written: its `type` picks the definition, and every required field must
+ * be there, since Grafana fills none in.
+ */
+export function validateExpressionSchema(model: Json, prefix = ""): SchemaProblem[] {
+  const def = typeof model.type === "string" ? EXPRESSION_DEFINITIONS[model.type] : undefined;
+  if (!def) {
+    return [{ path: `${prefix}/type`, message: `is ${JSON.stringify(model.type)}, not one of ${Object.keys(EXPRESSION_DEFINITIONS).join(", ")}`, severity: "error" }];
+  }
+  return check(model, "expr", def, false, prefix);
+}

package/src/schema.test.ts

@@ -2,7 +2,7 @@ import { describe, expect, test } from "vitest";
 import { readFileSync } from "fs";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
-import { GRAFANA_SCHEMA_PIN, SCHEMA_NAMES, schemaUrl } from "./pin";
+import { GRAFANA_SCHEMA_PIN, SCHEMA_NAMES, VENDORED_SCHEMA_NAMES, schemaUrl } from "./pin";
 import { digestMismatches, loadSchema } from "./spec/schemas";
 import { schemaModules } from "./codegen/generate";
 import { schemaModule, tsType } from "./codegen/schema-types";
@@ -13,7 +13,9 @@ const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
 describe("the schema pin", () => {
   test("names a commit and a digest for every vendored schema", () => {
     expect(GRAFANA_SCHEMA_PIN.commit).toMatch(/^[0-9a-f]{40}$/);
-    expect(Object.keys(GRAFANA_SCHEMA_PIN.files).sort()).toEqual([...SCHEMA_NAMES].sort());
+    expect(Object.keys(GRAFANA_SCHEMA_PIN.files).sort()).toEqual([...VENDORED_SCHEMA_NAMES].sort());
+    // Types come from the classic schemas only; dashboardv2 is vendored for the importer (#2947).
+    expect(VENDORED_SCHEMA_NAMES.filter((n) => !(SCHEMA_NAMES as readonly string[]).includes(n))).toEqual(["dashboardv2"]);
     expect(schemaUrl("stat")).toBe(`https://raw.githubusercontent.com/grafana/grafana-foundation-sdk/${GRAFANA_SCHEMA_PIN.commit}/jsonschema/stat.jsonschema.json`);
   });
 

package/src/serializer.test.ts

@@ -7,7 +7,7 @@ import { load } from "js-yaml";
 import type { Declarable } from "@intentius/chant/declarable";
 import type { SerializerResult } from "@intentius/chant/serializer";
 import { grafanaSerializer } from "./serializer";
-import { Datasource } from "./datasource";
+import { Datasource, ExternalDatasource } from "./datasource";
 import { Dashboard, DashboardProvider } from "./dashboard";
 import { StatPanel, TimeSeriesPanel } from "./panels";
 import { PromQuery } from "./query";
@@ -150,6 +150,18 @@ describe("grafana serializer", () => {
     expect(JSON.parse(out.primary).files).toEqual(Object.keys(out.files!).sort());
   });
 
+  test("an ExternalDatasource is referenced by uid, in panels and in another datasource's settings, and not provisioned", () => {
+    const loki = new ExternalDatasource({ type: "loki", uid: "loki-prod", name: "Loki (prod)" });
+    const tempo = new Datasource({ name: "Tempo", type: "tempo", jsonData: { tracesToLogsV2: { datasourceUid: loki } } });
+    const logs = new StatPanel({ datasource: loki });
+    const out = run({ loki, tempo, d: new Dashboard({ title: "D", panels: [logs] }) });
+    expect(JSON.parse(out.files!["dashboards/d.json"]).panels[0].datasource).toEqual({ type: "loki", uid: "loki-prod" });
+    const ds = load(out.files![DATASOURCES_FILE]) as { datasources: Array<{ name: string; jsonData?: unknown }> };
+    expect(ds.datasources.map((d) => d.name)).toEqual(["Tempo"]);
+    expect(ds.datasources[0].jsonData).toEqual({ tracesToLogsV2: { datasourceUid: "loki-prod" } });
+    expect(JSON.parse(out.primary).externalDatasources).toEqual([{ type: "loki", uid: "loki-prod", name: "Loki (prod)" }]);
+  });
+
   test("round trip: the emitted text parses back to the declared values", () => {
     const panel = new TimeSeriesPanel({ title: "Rate", datasource: prometheus, targets: [up], interval: "30s" });
     const out = run({ d: new Dashboard({ title: "Round trip", description: "desc", tags: ["a", "b"], panels: [panel] }) });

package/src/serializer.ts

@@ -9,13 +9,21 @@
  * - `provisioning/datasources/chant.yaml`: every declared datasource.
  * - `provisioning/dashboards/chant.yaml`: the provider that loads the
  *   dashboard files, a default one unless a `DashboardProvider` is declared.
+ * - `provisioning/alerting/chant.yaml`: rule groups, contact points, the
+ *   notification policy tree, mute timings and templates, when the build
+ *   declares any (see `alerting-build.ts`).
  *
  * Mount `provisioning/` at `/etc/grafana/provisioning` and `dashboards/` at
  * the provider's path (`/var/lib/grafana/dashboards` by default).
  *
- * The primary output is a small JSON index of what was built. Grafana's
- * files have no metadata channel chant could use without changing what
- * Grafana imports, so no ownership marker is stamped.
+ * The primary output is a small JSON index of what was built. The dashboard
+ * JSON carries no ownership marker, because Grafana keeps who manages a
+ * dashboard outside it, in the resource's metadata on its
+ * `dashboard.grafana.app` API. For a file-provisioned dashboard that metadata
+ * is the `grafana.app/managerId` annotation Grafana writes, whose value is the
+ * provider name in `provisioning/dashboards/chant.yaml`: `chant` unless a
+ * `DashboardProvider` names another. That name is the marker chant stamps at
+ * synthesis, and ./ownership.ts reads it back.
  */
 
 import type { Declarable } from "@intentius/chant/declarable";

package/src/skill-defs.ts

@@ -28,4 +28,21 @@ export const grafanaSkills = createSkillsLoader(import.meta.url, [
     description: "Load chant-built Grafana dashboards and datasources into a running Grafana through its provisioning directories, in Docker or Kubernetes",
     triggers: [{ type: "context" as const, value: "grafana provisioning" }],
   },
+  {
+    file: "chant-grafana-alerting.md",
+    name: "chant-grafana-alerting",
+    description:
+      "Declare Grafana-managed alert rules, server-side expressions, contact points, notification policies and mute timings, turn an Slo into burn-rate rules, and import Grafana's alerting exports",
+    triggers: [
+      { type: "context" as const, value: "grafana alerting" },
+      { type: "context" as const, value: "grafana alert rule" },
+      { type: "context" as const, value: "contact point" },
+    ],
+    examples: [
+      {
+        title: "An SLO's burn-rate alerts as Grafana-managed rules",
+        output: 'export const checkoutBurn = SloAlertRules({ slo: checkout, datasource: prometheus, folder: "SLOs" });',
+      },
+    ],
+  },
 ]);