@intentius/chant-lexicon-grafana 0.99.0 → 0.100.0

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

@@ -1,7 +1,7 @@
 /**
- * GRAF104: Two dashboards, datasources, panels, variables or queries share an id
+ * GRAF104: Two dashboards, datasources, folders, panels, variables or queries share an id
  *
- * Dashboard uids and datasource uids and names must be unique across the build, panel ids and variable names within a dashboard, and refIds within a panel. Grafana keeps one of two dashboards with the same uid and silently drops the other.
+ * Dashboard, folder and datasource uids and datasource names must be unique across the build, panel ids and variable names within a dashboard, and refIds within a panel. Grafana keeps one of two dashboards with the same uid and silently drops the other.
  */
 
 import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
@@ -9,7 +9,7 @@ import { grafanaDiagnostics } from "./grafana-helpers";
 
 export const graf104: PostSynthCheck = {
   id: "GRAF104",
-  description: "Two dashboards, datasources, panels, variables or queries share an id",
+  description: "Two dashboards, datasources, folders, panels, variables or queries share an id",
 
   check(ctx: PostSynthContext): PostSynthDiagnostic[] {
     return grafanaDiagnostics(ctx, "GRAF104");

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

@@ -1,7 +1,7 @@
 /**
- * GRAF106: A dashboard or datasource uid Grafana rejects, or a dashboard with no title
+ * GRAF106: A dashboard, folder or datasource uid Grafana rejects, or a dashboard with no title
  *
- * Grafana accepts uids of 1-40 letters, digits, - and _, and refuses to save a dashboard without a title.
+ * Grafana accepts uids of 1-40 letters, digits, - and _, refuses the folder uid general (its root), and refuses to save a dashboard without a title.
  */
 
 import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
@@ -9,7 +9,7 @@ import { grafanaDiagnostics } from "./grafana-helpers";
 
 export const graf106: PostSynthCheck = {
   id: "GRAF106",
-  description: "A dashboard or datasource uid Grafana rejects, or a dashboard with no title",
+  description: "A dashboard, folder or datasource uid Grafana rejects, or a dashboard with no title",
 
   check(ctx: PostSynthContext): PostSynthDiagnostic[] {
     return grafanaDiagnostics(ctx, "GRAF106");

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

@@ -0,0 +1,17 @@
+/**
+ * GRAF110: A panel or row repeats over a variable that cannot give it more than one value
+ *
+ * Grafana repeats a panel or row once per selected value of a query, custom, datasource or group by variable. Over an ad hoc, constant, interval, textbox or switch variable it shows the panel once and logs an error; over a query, custom or datasource variable with neither multi nor includeAll there is only ever one value. A repeat naming no variable is GRAF103.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { grafanaDiagnostics } from "./grafana-helpers";
+
+export const graf110: PostSynthCheck = {
+  id: "GRAF110",
+  description: "A panel or row repeats over a variable that cannot give it more than one value",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return grafanaDiagnostics(ctx, "GRAF110");
+  },
+};

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

@@ -33,10 +33,15 @@ function parse(text: string, name: string): unknown[] {
   }
 }
 
+/** The grafana serializer's primary output (build.ts `GrafanaIndex`), which lists the folders the build resolved. */
+function isGrafanaIndex(doc: unknown): doc is { folders?: Array<{ uid: string; title: string; path?: string; parentUid?: string }> } {
+  return typeof doc === "object" && doc !== null && typeof (doc as { grafanaSchema?: unknown }).grafanaSchema === "string" && Array.isArray((doc as { dashboards?: unknown }).dashboards);
+}
+
 /** 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 externalDatasources = [...(ctx.entities?.values() ?? [])].filter(isExternalDatasource).map(externalDatasourceRecord);
-  const out: GrafanaArtifacts = { dashboards: [], datasources: [], externalDatasources, providers: [], alerting: [] };
+  const out: GrafanaArtifacts = { dashboards: [], datasources: [], externalDatasources, providers: [], alerting: [], folders: [], deleteDatasources: [] };
   for (const [lexicon, output] of ctx.outputs) {
     const texts: Array<[string, string]> =
       typeof output === "string"
@@ -49,8 +54,13 @@ export function grafanaArtifacts(ctx: PostSynthContext): GrafanaArtifacts {
         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) {
+        else if (isGrafanaIndex(doc)) {
+          for (const f of doc.folders ?? []) if (f && typeof f.uid === "string" && typeof f.title === "string") out.folders!.push(f);
+        } else if (looksLikeDatasourceProvisioning(doc)) {
+          for (const d of doc.deleteDatasources ?? []) {
+            if (d && typeof d === "object" && typeof (d as { name?: unknown }).name === "string") out.deleteDatasources!.push(d as { name: string; orgId?: number });
+          }
+          for (const d of doc.datasources ?? []) {
             if (d && typeof d === "object" && typeof (d as ProvisionedDatasource).name === "string") {
               const ds = d as ProvisionedDatasource;
               out.datasources.push({ ...ds, uid: typeof ds.uid === "string" ? ds.uid : ds.name });

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

@@ -9,6 +9,7 @@ import { graf106 } from "./graf106";
 import { graf107 } from "./graf107";
 import { graf108 } from "./graf108";
 import { graf109 } from "./graf109";
+import { graf110 } from "./graf110";
 import { graf111 } from "./graf111";
 import { graf112 } from "./graf112";
 import { graf113 } from "./graf113";
@@ -25,6 +26,7 @@ export const postSynthChecks: PostSynthCheck[] = [
   graf107,
   graf108,
   graf109,
+  graf110,
   graf111,
   graf112,
   graf113,

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

@@ -6,11 +6,12 @@ import { makePostSynthCtxFromFiles, makePostSynthCtx } from "@intentius/chant-te
 import type { PostSynthCheck } from "@intentius/chant/lint/post-synth";
 import type { Declarable } from "@intentius/chant/declarable";
 import { grafanaSerializer } from "../../serializer";
-import { Datasource, ExternalDatasource } from "../../datasource";
+import { Datasource, DatasourceProvisioning, ExternalDatasource } from "../../datasource";
+import { Folder } from "../../folder";
 import { Dashboard, DashboardProvider } from "../../dashboard";
 import { HeatmapPanel, Row, StatPanel, TimeSeriesPanel, TablePanel, TextPanel } from "../../panels";
 import { LokiQuery, PromQuery, TempoQuery } from "../../query";
-import { DatasourceVariable, QueryVariable } from "../../variables";
+import { AdhocVariable, CustomVariable, DatasourceVariable, GroupByVariable, IntervalVariable, QueryVariable, SwitchVariable } from "../../variables";
 import { graf101 } from "./graf101";
 import { graf102 } from "./graf102";
 import { graf103 } from "./graf103";
@@ -20,6 +21,7 @@ import { graf106 } from "./graf106";
 import { graf107 } from "./graf107";
 import { graf108 } from "./graf108";
 import { graf109 } from "./graf109";
+import { graf110 } from "./graf110";
 import { graf115 } from "./graf115";
 import { panelUnits } from "../../validate-output";
 import { panelsOf } from "../../datasource-refs";
@@ -194,6 +196,18 @@ describe("GRAF103: undeclared variables", () => {
   });
 });
 
+describe("GRAF101, GRAF103 on ad hoc and group by variables", () => {
+  test("checks an ad hoc or group by variable's datasource like a query variable's", () => {
+    const d = dashboardJson([], [
+      { type: "adhoc", name: "f", datasource: { type: "prometheus", uid: "gone" }, filters: [] },
+      { type: "groupby", name: "by", datasource: { type: "prometheus", uid: "${nope}" } },
+    ]);
+    const ctx = ctxOfJson(d, [{ name: "Prometheus", type: "prometheus", uid: "prom" }]);
+    expect(graf101.check(ctx).map((x) => x.message)).toEqual([expect.stringContaining('variable "f" uses datasource uid "gone"')]);
+    expect(graf103.check(ctx).map((x) => x.message)).toEqual([expect.stringContaining('variable "by" datasource uses $nope')]);
+  });
+});
+
 describe("GRAF104: duplicates", () => {
   test("flags duplicate dashboard uids, datasource names and panel ids", () => {
     const again = new Datasource({ name: "Prometheus", type: "prometheus", uid: "prom-2" });
@@ -363,6 +377,54 @@ describe("GRAF108: PromQL syntax", () => {
   });
 });
 
+describe("GRAF110: repeats", () => {
+  test("flags a repeat over a variable Grafana cannot repeat over, and over one that holds one value", () => {
+    const ds = new DatasourceVariable({ name: "ds", pluginType: "prometheus" });
+    const w = new IntervalVariable({ name: "w", values: ["1m", "5m"] });
+    const on = new SwitchVariable({ name: "on" });
+    const f = new AdhocVariable({ name: "f", datasource: ds });
+    const env = new CustomVariable({ name: "env", values: ["a", "b"] });
+    const panels = [new StatPanel({ title: "by w", repeat: w }), new StatPanel({ title: "by on", repeat: on }), new StatPanel({ title: "by f", repeat: f }), new StatPanel({ title: "by env", repeat: env })];
+    const diags = graf110.check(ctxOf({ prometheus, d: new Dashboard({ title: "D", variables: [ds, w, on, f, env], panels }) }));
+    expect(diags.map((x) => [x.checkId, x.severity])).toEqual(Array(4).fill(["GRAF110", "warning"]));
+    expect(diags.map((x) => x.message)).toEqual([
+      expect.stringContaining('panel "by w" (id 1) repeats over $w, an interval variable, which Grafana cannot repeat over'),
+      expect.stringContaining("repeats over $on, a switch variable"),
+      expect.stringContaining("repeats over $f, an ad hoc variable"),
+      expect.stringContaining("repeats over $env, a custom variable with neither multi nor includeAll"),
+    ]);
+  });
+
+  test("checks a row's repeat too", () => {
+    const env = new CustomVariable({ name: "env", values: ["a", "b"] });
+    const row = new Row({ title: "Per env", repeat: env, panels: [new StatPanel({ title: "s" })] });
+    expect(graf110.check(ctxOf({ d: new Dashboard({ title: "D", variables: [env], panels: [row] }) })).map((x) => x.message)).toEqual([
+      expect.stringContaining('row "Per env" repeats over $env'),
+    ]);
+  });
+
+  test("passes a multi-value or include-all variable, a group by variable, and leaves an undeclared one to GRAF103", () => {
+    const env = new CustomVariable({ name: "env", values: ["a", "b"], multi: true });
+    const job = new QueryVariable({ name: "job", datasource: prometheus, query: { query: "label_values(up, job)", qryType: 1 }, includeAll: true });
+    const ds = new DatasourceVariable({ name: "ds", pluginType: "prometheus", multi: true });
+    const by = new GroupByVariable({ name: "by", datasource: prometheus });
+    const panels = [env, job, ds, by].map((v) => new StatPanel({ title: v.variableName, repeat: v }));
+    panels.push(new StatPanel({ title: "gone", repeat: "gone" }));
+    expect(graf110.check(ctxOf({ prometheus, d: new Dashboard({ title: "D", variables: [env, job, ds, by], panels }) }))).toEqual([]);
+  });
+});
+
+describe("GRAF108 on object-form variable queries", () => {
+  test("parses the query text of an object query sent to Prometheus", () => {
+    const ds = new DatasourceVariable({ name: "ds", pluginType: "prometheus" });
+    const bad = new QueryVariable({ name: "bad", datasource: ds, query: { qryType: 1, query: 'label_values(up{job="x", instance)', refId: "PrometheusVariableQueryEditor-VariableQuery" } });
+    const good = new QueryVariable({ name: "good", datasource: ds, query: { qryType: 4, query: 'kube_pod_info{namespace=~"$ns"}' } });
+    const ns = new CustomVariable({ name: "ns", values: ["a"] });
+    const diags = graf108.check(ctxOf({ prometheus, d: new Dashboard({ title: "D", variables: [ds, ns, bad, good] }) }));
+    expect(diags.map((x) => x.message)).toEqual([expect.stringContaining('variable "bad" query is not valid PromQL')]);
+  });
+});
+
 describe("GRAF108 over real Grafana exports", () => {
   const exportsDir = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "test", "fixtures", "exports");
   const files = readdirSync(exportsDir)
@@ -453,3 +515,38 @@ describe("GRAF115 over real Grafana exports and community dashboards", () => {
     expect(unitsSeen).toBeGreaterThan(200);
   });
 });
+
+describe("annotations, folders and datasource deletes (#2953)", () => {
+  const deploys = (datasource: unknown, extra: Record<string, unknown> = {}) => ({ name: "Deploys", datasource, ...extra }) as never;
+
+  test("GRAF101 flags an annotation on an undeclared datasource, GRAF102 one of another type", () => {
+    const d = new Dashboard({ title: "D", annotations: [deploys({ type: "prometheus", uid: "gone" })] });
+    expect(ids(graf101, ctxOf({ prometheus, d }))).toEqual([["GRAF101", "error"]]);
+    const t = new Dashboard({ title: "T", annotations: [deploys({ type: "loki", uid: "prometheus" })] });
+    expect(ids(graf102, ctxOf({ prometheus, t }))).toEqual([["GRAF102", "error"]]);
+    expect(ids(graf101, ctxOf({ prometheus, ok: new Dashboard({ title: "O", annotations: [deploys(prometheus)] }) }))).toEqual([]);
+  });
+
+  test("GRAF101 flags an ExternalDatasource the provisioning file deletes", () => {
+    const old = new ExternalDatasource({ type: "prometheus", uid: "old", name: "Old" });
+    const d = new Dashboard({ title: "D", panels: [new StatPanel({ datasource: old, targets: [up] })] });
+    const diags = graf101.check(ctxOf({ prometheus, old, d, settings: new DatasourceProvisioning({ deleteDatasources: [{ name: "Old" }] }) }));
+    // The panel's own ref and its query's, as for any undeclared datasource.
+    expect(diags.map((x) => [x.checkId, x.severity])).toEqual([["GRAF101", "error"], ["GRAF101", "error"]]);
+    expect(diags[0].message).toContain("deleteDatasources");
+  });
+
+  test("GRAF103 reads an annotation's query and datasource; GRAF108 parses its PromQL", () => {
+    const d = new Dashboard({ title: "D", annotations: [deploys(prometheus, { expr: "changes(up{job=\"$job\"}[5m] > 0" })] });
+    expect(ids(graf103, ctxOf({ prometheus, d }))).toEqual([["GRAF103", "error"]]);
+    expect(ids(graf108, ctxOf({ prometheus, d }))).toEqual([["GRAF108", "error"]]);
+  });
+
+  test("GRAF104 flags two folders with one uid; GRAF106 a folder uid Grafana refuses", () => {
+    const two = ctxOf({ a: new Dashboard({ title: "A", folder: "Team A" }), b: new Dashboard({ title: "B", folder: "team-a" }) });
+    expect(ids(graf104, two)).toEqual([["GRAF104", "error"]]);
+    expect(ids(graf106, ctxOf({ g: new Dashboard({ title: "G", folder: "General" }) }))).toEqual([["GRAF106", "error"]]);
+    expect(ids(graf106, ctxOf({ f: new Folder({ title: "F", uid: "not a uid" }) }))).toEqual([["GRAF106", "error"]]);
+    expect(ids(graf106, ctxOf({ f: new Folder({ title: "F" }), d: new Dashboard({ title: "D", folder: "F/G" }) }))).toEqual([]);
+  });
+});

package/src/load-cost.test.ts

@@ -0,0 +1,35 @@
+/**
+ * Importing the lexicon must not pay for schema validation (#2958): ajv
+ * loads the first time a schema is checked, and the schemas come from the
+ * generated `spec/schemas.gen.ts`, not from files beside the source.
+ */
+
+import { describe, expect, test } from "vitest";
+import { execFileSync } from "child_process";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { SCHEMA_NAMES } from "./pin";
+import { loadSchema } from "./spec/schemas";
+import { bundledSchema, schemaValidationUnavailable } from "./schema-validate";
+
+const srcDir = dirname(fileURLToPath(import.meta.url));
+const tsx = join(srcDir, "..", "..", "..", "node_modules", ".bin", "tsx");
+
+/** How many ajv modules a fresh process has loaded after importing `entries`. */
+function ajvModulesAfterImporting(...entries: string[]): number {
+  const imports = entries.map((e) => `import(${JSON.stringify(join(srcDir, e))})`).join(", ");
+  const script = `Promise.all([${imports}]).then(() => console.log(Object.keys(require.cache).filter((k) => k.includes("/ajv/")).length))`;
+  return Number(execFileSync(tsx, ["-e", script], { encoding: "utf-8" }).trim());
+}
+
+describe("load cost", () => {
+  test("importing the package root, its plugin or the validation subpath does not load ajv", () => {
+    // index.ts imports plugin.ts, whose post-synth checks reach schema-validate.ts.
+    expect(ajvModulesAfterImporting("index.ts", "validation.ts")).toBe(0);
+  });
+
+  test("validation reads the overlaid schemas from the generated module", () => {
+    expect(schemaValidationUnavailable()).toBeUndefined();
+    for (const name of SCHEMA_NAMES) expect(bundledSchema(name)).toEqual(loadSchema(name));
+  });
+});

package/src/op/activities/grafana-apply.e2e.test.ts

@@ -4,8 +4,9 @@
  * Per image, one project is built and applied with `grafanaApply`, the Op
  * activity, through its build output (the index and the dashboard files):
  *
- * 1. Apply: two folders, a library panel and three dashboards are created,
- *    each dashboard and folder labelled with the project's marker.
+ * 1. Apply: three folders (one nested in another, with a pinned uid), a
+ *    library panel and three dashboards are created, each dashboard and
+ *    folder labelled with the project's marker.
  * 2. Re-apply: nothing is created, and nothing is written.
  * 3. A panel title is edited in the source and applied: that dashboard is
  *    updated, the rest unchanged.
@@ -43,13 +44,15 @@ const MARKER_LABELS = { "app.kubernetes.io/managed-by": "chant", "chant.intentiu
 const LIBRARY_PANEL = { uid: "chant-e2e-burn", name: "Error budget burn", kind: 1, model: { type: "stat", title: "Error budget burn", description: "shared" } };
 
 function source(opts: { requestsTitle: string; withErrors: boolean }): string {
-  return `import { Dashboard, StatPanel } from "@intentius/chant-lexicon-grafana";
+  return `import { Dashboard, Folder, StatPanel } from "@intentius/chant-lexicon-grafana";
 
 export const requests = new StatPanel({ title: ${JSON.stringify(opts.requestsTitle)} });
 export const latency = new StatPanel({ title: "Latency" });
 export const fiveHundreds = new StatPanel({ title: "5xx" });
 export const apiOverview = new Dashboard({ title: "API overview", folder: "Team A", tags: ["api"], panels: [requests, latency] });
-${opts.withErrors ? `export const errors = new Dashboard({ title: "Errors", folder: "Team B", panels: [fiveHundreds] });\n` : ""}export const home = new Dashboard({ title: "Home" });
+${opts.withErrors ? `export const errors = new Dashboard({ title: "Errors", folder: "Team B", panels: [fiveHundreds] });\n` : ""}export const teamA = new Folder({ title: "Team A" });
+export const payments = new Folder({ title: "Payments", uid: "chant-e2e-payments", parent: teamA });
+export const home = new Dashboard({ title: "Home", folder: payments });
 `;
 }
 
@@ -112,7 +115,7 @@ describe.skipIf(!hasDocker).each(GRAFANA_IMAGES)(`grafanaApply applies, re-appli
 
   afterAll(() => scope.cleanup());
 
-  it("apply: creates the folders, the library panel and the dashboards, labelled with the marker", { timeout: 240_000 }, async () => {
+  it("apply: creates the folders, nested ones under their parent, the library panel and the dashboards, labelled with the marker", { timeout: 240_000 }, async () => {
     await buildProject({ requestsTitle: "Requests", withErrors: true });
     const out = await apply();
     expect(out.api).toMatch(/^apis\/v1(beta1)?$/);
@@ -121,6 +124,7 @@ describe.skipIf(!hasDocker).each(GRAFANA_IMAGES)(`grafanaApply applies, re-appli
       "created Dashboard/api-overview",
       "created Dashboard/errors",
       "created Dashboard/home",
+      "created Folder/chant-e2e-payments",
       "created Folder/team-a",
       "created Folder/team-b",
       "created LibraryPanel/chant-e2e-burn",
@@ -133,6 +137,11 @@ describe.skipIf(!hasDocker).each(GRAFANA_IMAGES)(`grafanaApply applies, re-appli
     const folder = (await grafana.api(out.applied.find((a) => a.name === "team-a")!.address)).body as { metadata: { labels: Record<string, string> }; spec: { title: string } };
     expect(folder.metadata.labels).toMatchObject(MARKER_LABELS);
     expect(folder.spec.title).toBe("Team A");
+    const nested = (await grafana.api("/api/folders/chant-e2e-payments")).body as { title: string; parentUid?: string; parents?: Array<{ uid: string }> };
+    expect(nested.title).toBe("Payments");
+    expect(nested.parentUid ?? nested.parents?.[0]?.uid).toBe("team-a");
+    const home = (await grafana.api(out.applied.find((a) => a.name === "home")!.address)).body as { metadata: { annotations: Record<string, string> } };
+    expect(home.metadata.annotations["grafana.app/folder"]).toBe("chant-e2e-payments");
     const connections = (await grafana.api(`/api/library-elements/${LIBRARY_PANEL.uid}/connections`)).body as { result: Array<{ connectionUid: string }> };
     expect(connections.result.map((c) => c.connectionUid)).toEqual(["api-overview"]);
   });

package/src/op/activities/grafana-apply.test.ts

@@ -1,10 +1,10 @@
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { afterAll, describe, expect, test } from "vitest";
 import { describeApplyConformance } from "@intentius/chant-test-utils";
 import { normalizeApply } from "@intentius/chant/apply";
-import { grafanaApply, readBuiltDashboards, resolveMarker, toApplyResult, type GrafanaApplyDeps } from "./grafana-apply";
+import { grafanaApply, readBuiltDashboards, readBuiltIndex, resolveMarker, toApplyResult, type GrafanaApplyDeps } from "./grafana-apply";
 import { emptyGrafana, writableGrafana, type WritableGrafanaState } from "../../api/fake-grafana-writes";
 import type { GrafanaHttp } from "../../api/client";
 
@@ -55,6 +55,20 @@ describe("readBuiltDashboards", () => {
     ]);
   });
 
+  test("reads the folders the index lists and each dashboard's folder uid (#2953)", () => {
+    const indexPath = buildOutput([{ json: dashboard("a"), folder: "Platform/Kubernetes" }]);
+    const index = JSON.parse(readFileSync(indexPath, "utf8")) as Json;
+    (index.dashboards as Json[])[0].folderUid = "k8s";
+    index.folders = [
+      { uid: "plat", title: "Platform", path: "Platform" },
+      { uid: "k8s", title: "Kubernetes", parentUid: "plat", path: "Platform/Kubernetes" },
+    ];
+    writeFileSync(indexPath, JSON.stringify(index));
+    const built = readBuiltIndex(indexPath);
+    expect(built.dashboards).toEqual([{ json: dashboard("a"), folder: "Platform/Kubernetes", folderUid: "k8s" }]);
+    expect(built.folders.map((f) => [f.uid, f.parentUid])).toEqual([["plat", undefined], ["k8s", "plat"]]);
+  });
+
   test("reads the grafana key of a combined multi-lexicon output", () => {
     expect(readBuiltDashboards(buildOutput([{ json: dashboard("a") }], { combined: true }))).toEqual([{ json: dashboard("a") }]);
   });

package/src/op/activities/grafana-apply.ts

@@ -29,6 +29,7 @@ import {
 import { bindGrafana, GrafanaBindingError, type BindOptions } from "../../api/bind";
 import type { GrafanaHttp } from "../../api/client";
 import { applyGrafana, parseDashboardFile, planFromDashboards, planRefs, type BuiltDashboardInput, type GrafanaApplyOutcome } from "../../api/apply";
+import type { FolderPlan } from "../../api/folders";
 
 export type { GrafanaApplyOutcome } from "../../api/apply";
 
@@ -74,16 +75,40 @@ function isObject(v: unknown): v is Json {
  * it. Pure but for the file reads.
  */
 export function readBuiltDashboards(indexPath: string, read: (path: string) => string = (p) => readFileSync(p, "utf8")): BuiltDashboardInput[] {
+  return readBuiltIndex(indexPath, read).dashboards;
+}
+
+/** The grafana index inside a build output: the index itself, or its `grafana` key in a multi-lexicon output. */
+function grafanaIndexOf(indexPath: string, read: (path: string) => string): Json {
   const raw = parseDashboardFile(read(indexPath), indexPath);
   const index = isObject(raw.grafana) && Array.isArray(raw.grafana.dashboards) ? raw.grafana : raw;
   if (!Array.isArray(index.dashboards)) throw new Error(`grafana apply: ${indexPath} is not a grafana build index (it has no "dashboards" list)`);
+  return index;
+}
+
+/**
+ * The dashboards a build wrote, with their folders, and the folders its
+ * index lists (every level of every folder, `Folder`s holding no dashboard
+ * included). An index written before folders were listed has none, and the
+ * plan derives them from the dashboards' paths.
+ */
+export function readBuiltIndex(indexPath: string, read: (path: string) => string = (p) => readFileSync(p, "utf8")): { dashboards: BuiltDashboardInput[]; folders: FolderPlan[] } {
+  const index = grafanaIndexOf(indexPath, read);
   const dir = dirname(indexPath);
-  return index.dashboards.map((entry, i) => {
+  const dashboards = (index.dashboards as unknown[]).map((entry, i) => {
     if (!isObject(entry) || typeof entry.file !== "string") throw new Error(`grafana apply: ${indexPath} dashboards[${i}] names no file`);
     const file = join(dir, entry.file);
     const json = parseDashboardFile(read(file), file);
-    return { json, ...(typeof entry.folder === "string" && entry.folder !== "" ? { folder: entry.folder } : {}) };
+    const folder = typeof entry.folder === "string" && entry.folder !== "" ? entry.folder : undefined;
+    const folderUid = folder && typeof entry.folderUid === "string" && entry.folderUid !== "" ? entry.folderUid : undefined;
+    return { json, ...(folder ? { folder } : {}), ...(folderUid ? { folderUid } : {}) };
   });
+  const folders: FolderPlan[] = (Array.isArray(index.folders) ? index.folders : []).flatMap((f: unknown) =>
+    isObject(f) && typeof f.uid === "string" && typeof f.title === "string" && typeof f.path === "string"
+      ? [{ uid: f.uid, title: f.title, path: f.path, ...(typeof f.parentUid === "string" ? { parentUid: f.parentUid } : {}) }]
+      : [],
+  );
+  return { dashboards, folders };
 }
 
 async function loadConfig(cwd: string): Promise<Pick<ChantConfig, "grafana" | "ownership"> | undefined> {
@@ -116,7 +141,8 @@ export function resolveMarker(args: Pick<GrafanaApplyArgs, "stack" | "ownershipE
  * with the binding's reason.
  */
 export async function grafanaApply(args: GrafanaApplyArgs, signal?: AbortSignal, deps: GrafanaApplyDeps = {}): Promise<GrafanaApplyOutcome> {
-  const plan = planFromDashboards(readBuiltDashboards(args.indexPath));
+  const built = readBuiltIndex(args.indexPath);
+  const plan = planFromDashboards(built.dashboards, built.folders);
   const config = deps.config ?? (await loadConfig(args.cwd ?? process.cwd()));
   const marker = resolveMarker(args, config);
   const bind: BindOptions = {

package/src/op/activities/index.ts

@@ -4,5 +4,5 @@
  * API applier (`grafanaApply`, #2948) and its envelope projection
  * (`toApplyResult`), which core's apply activity looks up by name.
  */
-export { grafanaApply, toApplyResult, readBuiltDashboards, resolveMarker } from "./grafana-apply";
+export { grafanaApply, toApplyResult, readBuiltDashboards, readBuiltIndex, resolveMarker } from "./grafana-apply";
 export type { GrafanaApplyArgs, GrafanaApplyDeps, GrafanaApplyOutcome } from "./grafana-apply";

package/src/ownership.ts

@@ -41,6 +41,7 @@ import {
 } from "@intentius/chant/ownership";
 import { DASHBOARD_PROVIDER_TYPE } from "./dashboard";
 import type { LiveDashboard } from "./api/dashboards";
+import type { LiveFolder } from "./api/folders";
 
 /** The label keys chant's marker uses on a `dashboard.grafana.app` resource. */
 export const GRAFANA_OWNERSHIP_KEYS: ChannelKeys = LABEL_OWNERSHIP_KEYS;
@@ -101,3 +102,21 @@ export function dashboardOwnership(
   }
   return { ownership: "foreign" };
 }
+
+/**
+ * A folder's ownership verdict, read the way a dashboard's is: chant's labels
+ * (the API applier's), else the manager annotations Grafana writes on a
+ * folder that file provisioning made for one of this project's providers.
+ * A folder read over `/api/folders` (Grafana 11) has neither: `unknown`.
+ */
+export function folderOwnership(folder: LiveFolder, providers: ReadonlySet<string>): { ownership: OwnershipVerdict; marker?: OwnershipMarker } {
+  if (folder.via === "legacy") return { ownership: "unknown" };
+  if (hasOwnershipMarker(folder.labels, GRAFANA_OWNERSHIP_KEYS)) {
+    const marker = readOwnership(folder.labels, GRAFANA_OWNERSHIP_KEYS);
+    return { ownership: classifyOwnership(folder.labels, GRAFANA_OWNERSHIP_KEYS), ...(marker ? { marker } : {}) };
+  }
+  const annotations = folder.annotations ?? {};
+  const manager = annotations[MANAGER_ID_ANNOTATION];
+  if (annotations[MANAGED_BY_ANNOTATION] === FILE_PROVISIONING_MANAGER && manager !== undefined && providers.has(manager)) return { ownership: "owned" };
+  return { ownership: "foreign" };
+}

package/src/panels.test.ts

@@ -4,12 +4,14 @@ import { Dashboard } from "./dashboard";
 import { renderDashboard } from "./build";
 import { validateDashboardSchema } from "./schema-validate";
 import { SCHEMA_NAMES } from "./pin";
+import { registeredQueries } from "./query";
 
 const builtins = panels.registeredPanels().filter((d) => d.builtin);
 
 describe("built-in panels", () => {
   test("every panel type Grafana ships with a schema at the pin has a class", () => {
-    const panelSchemas = SCHEMA_NAMES.filter((n) => !["dashboard", "prometheus", "tempo", "loki", "expr"].includes(n));
+    const querySchemas = new Set<string>(registeredQueries().flatMap((d) => (d.schema ? [d.schema] : [])));
+    const panelSchemas = SCHEMA_NAMES.filter((n) => n !== "dashboard" && n !== "expr" && !querySchemas.has(n));
     expect(builtins.map((d) => d.schema).filter(Boolean).sort()).toEqual([...panelSchemas].sort());
   });
 

package/src/pin.ts

@@ -59,6 +59,12 @@ export const SCHEMA_NAMES = [
   "prometheus",
   "tempo",
   "loki",
+  "elasticsearch",
+  "cloudwatch",
+  "azuremonitor",
+  "googlecloudmonitoring",
+  "bigquery",
+  "grafanapyroscope",
   "expr",
 ] as const;
 
@@ -108,6 +114,12 @@ export const GRAFANA_SCHEMA_PIN: GrafanaSchemaPin = Object.freeze({
     prometheus: "726fc97eeb1e37791dbbf988c3cf40de17bb8e623926e6979c4a3f947cb1af87",
     tempo: "21aec4c333c9b8e5e9228e85a6225c76161975abb54002e6f12e919e3b4e54ae",
     loki: "03b81d6b952e3d31785c4b52637e2b7b1c170cc2ea8ec7ec671c21599508e31b",
+    elasticsearch: "126b0e04116877f468df7474ad6f75167cf9c54feb125534211fbe1915e6421e",
+    cloudwatch: "06d50341c82420865f3f58bfd3e3081cd90fb625f1d275bb7ba0230033f9db3f",
+    azuremonitor: "fe0f2fc01ff626dec7ce17a0e3dbb2e76f51f20539c73bbded46bbc4c2d3e262",
+    googlecloudmonitoring: "e1f2e2086d4216f22aca84def440b6a31a76e074727aa2ea3d2d10671e68834b",
+    bigquery: "939a0a6aee2c98fd8f690659e17060ff2b5bad1b22437e3449741ce0acc5abe4",
+    grafanapyroscope: "297db04efc4f9501ffa729acd9e02e484998bc4d823c7da362e401faceed64a2",
     expr: "b1f1c1e4f6bf00f0fb4cb32b5bcc1b0e91fad9b7ad9354ecb791322bd97a5564",
     dashboardv2: "a2cfb8b731ff9f48c41f5aa06ade134cf0d93ab9f6f0567a34a4bc39a9fd984e",
   }),

package/src/plugin.test.ts

@@ -16,7 +16,7 @@ describe("grafana plugin", () => {
 
   it("ships lint rules and post-synth checks, all under the GRAF prefix", () => {
     const ids = [...grafanaPlugin.lintRules!().map((r) => r.id), ...grafanaPlugin.postSynthChecks!().map((c) => c.id)];
-    expect(ids).toEqual(["GRAF001", "GRAF002", "GRAF101", "GRAF102", "GRAF103", "GRAF104", "GRAF105", "GRAF106", "GRAF107", "GRAF108", "GRAF109", "GRAF111", "GRAF112", "GRAF113", "GRAF114", "GRAF115"]);
+    expect(ids).toEqual(["GRAF001", "GRAF002", "GRAF101", "GRAF102", "GRAF103", "GRAF104", "GRAF105", "GRAF106", "GRAF107", "GRAF108", "GRAF109", "GRAF110", "GRAF111", "GRAF112", "GRAF113", "GRAF114", "GRAF115"]);
   });
 
   it("catalogues every rule and check for chant audit, and nothing else", () => {
@@ -38,10 +38,17 @@ describe("grafana plugin", () => {
 
   it("loads its skills with content", () => {
     const skills = grafanaPlugin.skills!();
-    expect(skills.map((s) => s.name)).toEqual(["chant-grafana", "chant-grafana-provisioning", "chant-grafana-alerting"]);
+    expect(skills.map((s) => s.name)).toEqual(["chant-grafana", "chant-grafana-provisioning", "chant-grafana-alerting", "chant-grafana-operations"]);
     for (const s of skills) expect(s.content.length).toBeGreaterThan(200);
   });
 
+  it("offers a default init template and three named ones", () => {
+    const names = [undefined, "red", "k8s-pods", "slo"];
+    const sets = names.map((n) => grafanaPlugin.initTemplates!(n));
+    expect(new Set(sets).size).toBe(4);
+    for (const set of sets) expect(Object.keys(set.src).length).toBeGreaterThan(0);
+  });
+
   it("registers namespaced MCP contributions", async () => {
     expect(grafanaPlugin.mcpTools!().map((t) => t.name)).toEqual(["grafana:diff"]);
     const [resource] = grafanaPlugin.mcpResources!();

package/src/plugin.ts

@@ -14,6 +14,7 @@ import { GrafanaParser } from "./import/parser";
 import { GrafanaGenerator } from "./import/generator";
 import { dashboardImporter } from "./import/embedded";
 import { grafanaSkills } from "./skill-defs";
+import { DEFAULT_TEMPLATE, K8S_PODS_TEMPLATE, RED_TEMPLATE, SLO_TEMPLATE } from "./init-templates";
 import { BUILTIN_CATALOG } from "./catalog";
 import { GRAFANA_SCHEMA_PIN } from "./pin";
 import { compositeCatalog } from "./composites/catalog";
@@ -129,6 +130,14 @@ export const grafanaPlugin: LexiconPlugin = {
     return [catalogResource];
   },
 
+  // `chant init --lexicon grafana [--template red|k8s-pods|slo]`; see ./init-templates.ts.
+  initTemplates(template?: string) {
+    if (template === "red") return RED_TEMPLATE;
+    if (template === "k8s-pods") return K8S_PODS_TEMPLATE;
+    if (template === "slo") return SLO_TEMPLATE;
+    return DEFAULT_TEMPLATE;
+  },
+
   detectTemplate(data: unknown) {
     return detectTemplate(data);
   },

package/src/promql-check.ts

@@ -164,7 +164,11 @@ function usesOf(dashboard: Json, known: ReadonlyMap<string, KnownDatasource>, li
       const expr = use.target?.expr;
       if (typeof expr !== "string" || expr.trim() === "") continue;
       out.push({ where: library ? `library panel "${library}" query ${String(use.target?.refId ?? "?")}` : use.where, expr });
-    } else if (use.kind === "variable" && use.variable && !library) {
+    } else if (use.kind === "annotation" && use.annotation) {
+      // A Prometheus annotation keeps its query in `target.expr`, or at the top level when saved before Grafana 10.
+      const expr = use.target?.expr ?? use.annotation.expr;
+      if (typeof expr === "string" && expr.trim() !== "") out.push({ where: `${use.where} query`, expr });
+    } else if (use.kind === "variable" && use.variable?.type === "query" && !library) {
       const text = variableQueryText(use.variable);
       if (text) for (const expr of variablePromql(text)) out.push({ where: `${use.where} query`, expr });
     }