@intentius/chant-lexicon-grafana 0.99.0 → 0.100.0

package/src/generated/lexicon-grafana.json

@@ -1,4 +1,9 @@
 {
+  "AdhocVariable": {
+    "resourceType": "Grafana::Variable::adhoc",
+    "kind": "resource",
+    "lexicon": "grafana"
+  },
   "AlertListPanel": {
     "resourceType": "Grafana::Panel::alertlist",
     "kind": "resource",
@@ -19,6 +24,11 @@
     "kind": "resource",
     "lexicon": "grafana"
   },
+  "AzureMonitorQuery": {
+    "resourceType": "Grafana::Query::grafana-azure-monitor-datasource",
+    "kind": "resource",
+    "lexicon": "grafana"
+  },
   "BarChartPanel": {
     "resourceType": "Grafana::Panel::barchart",
     "kind": "resource",
@@ -29,6 +39,11 @@
     "kind": "resource",
     "lexicon": "grafana"
   },
+  "BigQueryQuery": {
+    "resourceType": "Grafana::Query::grafana-bigquery-datasource",
+    "kind": "resource",
+    "lexicon": "grafana"
+  },
   "CanvasPanel": {
     "resourceType": "Grafana::Panel::canvas",
     "kind": "resource",
@@ -39,6 +54,16 @@
     "kind": "resource",
     "lexicon": "grafana"
   },
+  "CloudMonitoringQuery": {
+    "resourceType": "Grafana::Query::stackdriver",
+    "kind": "resource",
+    "lexicon": "grafana"
+  },
+  "CloudWatchQuery": {
+    "resourceType": "Grafana::Query::cloudwatch",
+    "kind": "resource",
+    "lexicon": "grafana"
+  },
   "ConstantVariable": {
     "resourceType": "Grafana::Variable::constant",
     "kind": "resource",
@@ -69,11 +94,21 @@
     "kind": "resource",
     "lexicon": "grafana"
   },
+  "DatasourceProvisioning": {
+    "resourceType": "Grafana::DatasourceProvisioning",
+    "kind": "resource",
+    "lexicon": "grafana"
+  },
   "DatasourceVariable": {
     "resourceType": "Grafana::Variable::datasource",
     "kind": "resource",
     "lexicon": "grafana"
   },
+  "ElasticsearchQuery": {
+    "resourceType": "Grafana::Query::elasticsearch",
+    "kind": "resource",
+    "lexicon": "grafana"
+  },
   "ExternalDatasource": {
     "resourceType": "Grafana::ExternalDatasource",
     "kind": "resource",
@@ -84,6 +119,11 @@
     "kind": "resource",
     "lexicon": "grafana"
   },
+  "Folder": {
+    "resourceType": "Grafana::Folder",
+    "kind": "resource",
+    "lexicon": "grafana"
+  },
   "GaugePanel": {
     "resourceType": "Grafana::Panel::gauge",
     "kind": "resource",
@@ -94,6 +134,11 @@
     "kind": "resource",
     "lexicon": "grafana"
   },
+  "GroupByVariable": {
+    "resourceType": "Grafana::Variable::groupby",
+    "kind": "resource",
+    "lexicon": "grafana"
+  },
   "HeatmapPanel": {
     "resourceType": "Grafana::Panel::heatmap",
     "kind": "resource",
@@ -124,11 +169,21 @@
     "kind": "resource",
     "lexicon": "grafana"
   },
+  "MSSQLQuery": {
+    "resourceType": "Grafana::Query::mssql",
+    "kind": "resource",
+    "lexicon": "grafana"
+  },
   "MuteTiming": {
     "resourceType": "Grafana::MuteTiming",
     "kind": "resource",
     "lexicon": "grafana"
   },
+  "MySQLQuery": {
+    "resourceType": "Grafana::Query::mysql",
+    "kind": "resource",
+    "lexicon": "grafana"
+  },
   "NodeGraphPanel": {
     "resourceType": "Grafana::Panel::nodeGraph",
     "kind": "resource",
@@ -149,11 +204,21 @@
     "kind": "resource",
     "lexicon": "grafana"
   },
+  "PostgresQuery": {
+    "resourceType": "Grafana::Query::grafana-postgresql-datasource",
+    "kind": "resource",
+    "lexicon": "grafana"
+  },
   "PromQuery": {
     "resourceType": "Grafana::Query::prometheus",
     "kind": "resource",
     "lexicon": "grafana"
   },
+  "PyroscopeQuery": {
+    "resourceType": "Grafana::Query::grafana-pyroscope-datasource",
+    "kind": "resource",
+    "lexicon": "grafana"
+  },
   "QueryVariable": {
     "resourceType": "Grafana::Variable::query",
     "kind": "resource",
@@ -194,6 +259,11 @@
     "kind": "resource",
     "lexicon": "grafana"
   },
+  "SwitchVariable": {
+    "resourceType": "Grafana::Variable::switch",
+    "kind": "resource",
+    "lexicon": "grafana"
+  },
   "TablePanel": {
     "resourceType": "Grafana::Panel::table",
     "kind": "resource",

package/src/import/generated-types.e2e.test.ts

@@ -18,7 +18,7 @@ import { join } from "path";
 import * as ts from "typescript";
 import { GrafanaParser } from "./parser";
 import { GrafanaGenerator } from "./generator";
-import { ALERTING, COMMUNITY, KUBE_PROMETHEUS, UI_EXPORTS, V2_EXPORTS, exampleOutputs, pkgDir, read, removeDir, repoRoot, writeFiles } from "./testdata/fixtures";
+import { ALERTING, COMMUNITY, KUBE_PROMETHEUS, PROVISIONING, UI_EXPORTS, V2_EXPORTS, exampleOutputs, pkgDir, read, removeDir, repoRoot, writeFiles } from "./testdata/fixtures";
 
 type Files = Array<{ path: string; content: string }>;
 
@@ -68,13 +68,25 @@ function byProperty(errors: string[]): Record<string, number> {
 
 describe("the generated source type-checks against the lexicon's types", () => {
   test("Grafana's UI exports, the v2 dashboards and the examples' dashboards type-check clean", async () => {
-    const projects: Record<string, Files> = Object.fromEntries([...UI_EXPORTS, ...V2_EXPORTS].map((f) => [f, generate(read(f))]));
+    const projects: Record<string, Files> = Object.fromEntries(
+      [...UI_EXPORTS, ...V2_EXPORTS, "provisioning/typed-plugins.datasources.yaml"].map((f) => [f, generate(read(f))]),
+    );
     for (const [name, text] of await exampleOutputs()) {
       if (/^[^/]+\/dashboards\/.*\.json$/.test(name)) projects[name] = generate(text);
     }
     expect(typeErrors(projects)).toEqual([]);
   }, 180_000);
 
+  test("real-world provisioning files: settings the pinned plugins no longer read are where tsc points", () => {
+    const found: Record<string, Record<string, number>> = {};
+    for (const file of PROVISIONING) found[file] = byProperty(typeErrors({ [file]: generate(read(file)) }));
+    expect(found).toEqual({
+      "provisioning/typed-plugins.datasources.yaml": {},
+      // Tempo's lokiSearch, which tempo 13.1.5 (bundled with Grafana 13.2.2) no longer reads.
+      "provisioning/docker-otel-lgtm.datasources.yaml": { lokiSearch: 1 },
+    });
+  }, 120_000);
+
   test("alerting provisioning files, and what the alerting example builds, type-check clean", async () => {
     const projects: Record<string, Files> = Object.fromEntries(ALERTING.map((f) => [f, generate(read(f))]));
     for (const [name, text] of await exampleOutputs()) {
@@ -90,7 +102,7 @@ describe("the generated source type-checks against the lexicon's types", () => {
     expect(found).toEqual({
       "community/node-exporter-full.json": { step: 273, metric: 1 },
       "community/k8s-views-global.json": {},
-      "community/k8s-views-pods.json": { footer: 3 },
+      "community/k8s-views-pods.json": { wrapText: 2 },
       "community/traefik.json": {},
       "community/redis.json": { metric: 11, step: 6, time_options: 1, unitScale: 13 },
       "community/prometheus-2-stats.json": { metric: 3, now: 1, step: 18 },

package/src/import/generator.ts

@@ -405,6 +405,7 @@ export function generatePlanModules(plan: Plan): {
         classRef = className;
       }
       mod.declarables++;
+      const typed = d.typeArguments && d.typeArguments.length > 0 ? `${classRef}<${d.typeArguments.join(", ")}>` : classRef;
       const entries: Array<[string, string]> = [];
       for (const [key, raw] of Object.entries(d.props ?? {})) {
         if (raw === undefined) continue;
@@ -415,7 +416,7 @@ export function generatePlanModules(plan: Plan): {
         }
         mod.types.add("PropsOf");
         const cn = constName(`${name}${pascal(key) || "Value"}`);
-        const head = `const ${cn}: PropsOf<typeof ${classRef}>[${JSON.stringify(key)}] = `;
+        const head = `const ${cn}: PropsOf<typeof ${typed}>[${JSON.stringify(key)}] = `;
         lines.push(`${head}${tsLiteral(value, 0, head.length)};`);
         entries.push([key, cn]);
       }

package/src/import/mappings.ts

@@ -8,13 +8,19 @@
  *   in `panels.ts` is used by the importer with no change here. Any other
  *   type is declared in the imported source with `definePanel`.
  * - Query types (#2951): the same, through `registeredQueries()`, keyed by
- *   datasource plugin type; any other type gets a `defineQuery`.
+ *   datasource plugin type or one of its `aliases` (`postgres`); any other
+ *   type gets a `defineQuery`.
+ * - Datasource links in a provisioning file (#2951): `JSONDATA_LINKS` in
+ *   `../datasource-settings.ts` lists the `jsonData` fields that hold another
+ *   datasource's uid and the plugin types each takes; the parser turns such a
+ *   uid into a reference. Add an entry with the `LinkedDatasource` field.
  * - Variable types (#2952): `VARIABLE_MAPPINGS` has one entry per type the
- *   lexicon has a class for. A type with no entry (adhoc, groupby, switch)
- *   is reported and left out. Add an entry when the class lands.
- * - Dashboard and panel fields (#2953 annotations, and any new prop):
- *   `DASHBOARD_FIELDS`, `PANEL_FIELDS` and `ROW_FIELDS` list the JSON keys
- *   copied onto a prop as they are. A key in none of the tables, and not
+ *   lexicon has a class for. A type with no entry (`system`, `snapshot`,
+ *   which Grafana does not save) is reported and left out.
+ * - Dashboard and panel fields (any new prop): `DASHBOARD_FIELDS`,
+ *   `PANEL_FIELDS` and `ROW_FIELDS` list the JSON keys copied onto a prop as
+ *   they are. Annotations (#2953) are read by the parser's `annotations()`,
+ *   which resolves their datasources. A key in none of the tables, and not
  *   handled by the parser, is reported and left out, unless it is at the
  *   value Grafana assumes when it is missing (see `./normalize.ts`).
  */
@@ -22,7 +28,7 @@
 import { registeredPanels, type PanelDefinition } from "../panels";
 import { registeredQueries, type QueryDefinition } from "../query";
 import type { VariableHide } from "../variables";
-import { splitValues } from "./normalize";
+import { deepEqual, splitValues } from "./normalize";
 
 type Json = Record<string, unknown>;
 
@@ -96,7 +102,7 @@ export function builtinPanelFor(type: string): PanelDefinition | undefined {
 
 /** The class a query to a datasource of this plugin type is declared with, when chant ships one. */
 export function builtinQueryFor(datasourceType: string): QueryDefinition | undefined {
-  return registeredQueries().find((d) => d.builtin && d.datasourceType === datasourceType);
+  return registeredQueries().find((d) => d.builtin && (d.datasourceType === datasourceType || d.aliases?.includes(datasourceType)));
 }
 
 /**
@@ -166,29 +172,15 @@ export const VARIABLE_MAPPINGS: Readonly<Record<string, VariableMapping>> = {
     keys: ["datasource", "query", "definition", "regex", "refresh", "sort", "options", "current", ...MULTI_KEYS],
     convert(ctx) {
       const { json } = ctx;
-      let query = str(json.query);
-      if (query === undefined && json.query !== null && typeof json.query === "object") {
-        const obj = json.query as Json;
-        query = str(obj.query);
-        if (query === undefined) {
-          ctx.dropVariable("its query is an object with no query string, which QueryVariable cannot hold yet (#2952)");
-          return undefined;
-        }
-        // refId is the editor's own id for the query, which Grafana gives the string form back.
-        const rest = Object.keys(obj).filter((k) => k !== "query" && k !== "refId");
-        ctx.replace(
-          "query",
-          query,
-          rest.length === 0 ? undefined : `is an object; it is written as its query string, and its ${rest.join(" and ")} ${rest.length === 1 ? "is" : "are"} not carried (#2952)`,
-        );
-      }
-      query ??= "";
-      if (nonEmpty(json.definition) && json.definition !== query) ctx.drop("definition", `(it differs from the query, which is kept)`);
+      // The object form (Prometheus writes `{ qryType, query, refId }`) is carried as it is: the datasource reads all of it.
+      const query: string | Json = json.query !== null && typeof json.query === "object" && !Array.isArray(json.query) ? (json.query as Json) : (str(json.query) ?? "");
+      const text = typeof query === "string" ? query : str(query.query);
       const refresh = typeof json.refresh === "number" ? json.refresh : 1;
       if (refresh === 0 && nonEmpty(json.options)) {
         ctx.drop("options", "(QueryVariable does not store options; with refresh never, Grafana shows none until it is refreshed)");
       }
       const out: Json = { datasource: ctx.datasource(json.datasource, `${ctx.path}/datasource`), query };
+      if (nonEmpty(json.definition) && json.definition !== text) out.definition = json.definition;
       if (out.datasource === undefined) {
         ctx.dropVariable("it has no datasource chant can refer to, and QueryVariable needs one");
         return undefined;
@@ -258,7 +250,87 @@ export const VARIABLE_MAPPINGS: Readonly<Record<string, VariableMapping>> = {
       return value === "" ? {} : { value };
     },
   },
+  adhoc: {
+    className: "AdhocVariable",
+    keys: ["datasource", "filters", "baseFilters", "defaultKeys", "allowCustomValue", "enableGroupBy", "current", "options"],
+    convert(ctx) {
+      const { json } = ctx;
+      const out: Json = { datasource: ctx.datasource(json.datasource, `${ctx.path}/datasource`) };
+      if (out.datasource === undefined) {
+        ctx.dropVariable("it has no datasource chant can refer to, and AdhocVariable needs one");
+        return undefined;
+      }
+      if (filters(json.filters)) out.filters = json.filters;
+      if (filters(json.baseFilters)) out.baseFilters = json.baseFilters;
+      if (Array.isArray(json.defaultKeys)) out.defaultKeys = json.defaultKeys;
+      if (json.allowCustomValue === false) out.allowCustomValue = false;
+      if (json.enableGroupBy === true) out.enableGroupBy = true;
+      return out;
+    },
+  },
+  groupby: {
+    className: "GroupByVariable",
+    // A group by variable is always multi-value; Grafana reads no `multi` on it.
+    keys: ["datasource", "options", "current", "defaultValue", "allowCustomValue", "multi"],
+    convert(ctx) {
+      const { json } = ctx;
+      const out: Json = { datasource: ctx.datasource(json.datasource, `${ctx.path}/datasource`) };
+      if (out.datasource === undefined) {
+        ctx.dropVariable("it has no datasource chant can refer to, and GroupByVariable needs one");
+        return undefined;
+      }
+      if (Array.isArray(json.options) && json.options.length > 0) out.options = json.options.map(keyOption);
+      const def = json.defaultValue as Json | undefined;
+      if (nonEmpty(def)) out.defaultValue = Array.isArray(def!.value) && deepEqual(def!.text, def!.value) ? def!.value : def;
+      // The build writes the default as the current selection when there is no other.
+      if (nonEmpty(json.current) && !deepEqual(json.current, def)) out.current = json.current;
+      if (json.allowCustomValue === false) out.allowCustomValue = false;
+      return out;
+    },
+  },
+  switch: {
+    className: "SwitchVariable",
+    // Grafana reads no `query` on a switch (the v2 down-conversion writes an empty one).
+    keys: ["current", "options", "query"],
+    convert(ctx) {
+      const { json } = ctx;
+      const options = Array.isArray(json.options) ? json.options : [];
+      // Grafana keeps the enabled value first and the disabled value second.
+      const on = firstValue(options[0]) ?? "true";
+      const off = firstValue(options[1]) ?? "false";
+      const out: Json = {};
+      if (on !== "true") out.enabledValue = on;
+      if (off !== "false") out.disabledValue = off;
+      const value = firstValue(json.current);
+      if (value === on) out.enabled = true;
+      else if (value !== off) {
+        ctx.replace("current", { text: off, value: off }, `is ${value === undefined ? "missing" : `"${value}", neither the enabled nor the disabled value`}; the switch starts off`);
+      }
+      return out;
+    },
+  },
 };
 
+/** An ad hoc filter list, or undefined when it is empty (the build writes `[]`). */
+function filters(v: unknown): unknown[] | undefined {
+  return Array.isArray(v) && v.length > 0 ? v : undefined;
+}
+
+/** A `{ text, value }` option as the shortest prop that builds back to it: the value when the text is the same. */
+function keyOption(o: unknown): unknown {
+  if (o && typeof o === "object" && !Array.isArray(o)) {
+    const { text, value, ...rest } = o as Json;
+    if (Object.keys(rest).length === 0 && typeof value === "string" && text === value) return value;
+  }
+  return o;
+}
+
+/** The first value of a `VariableOption`'s value, which may be a list. */
+function firstValue(o: unknown): string | undefined {
+  if (!o || typeof o !== "object") return undefined;
+  const v = (o as Json).value;
+  return typeof v === "string" ? v : Array.isArray(v) && typeof v[0] === "string" ? v[0] : undefined;
+}
+
 /** Keys every variable type reads: the ones `CommonVariableProps` has, and `type`. */
 export const COMMON_VARIABLE_KEYS: readonly string[] = ["type", "name", "label", "description", "hide", "skipUrlSync"];

package/src/import/model.ts

@@ -59,6 +59,13 @@ export interface Declaration {
   readonly className?: string;
   /** For `new`: the id of the `CustomClass` declaring `className`, when it is not a package export. */
   readonly customClass?: string;
+  /**
+   * For `new`: type arguments for the class, as TypeScript source. The
+   * consts lifted out of the props are typed `PropsOf<typeof Class<...>>`,
+   * so a `Datasource<"prometheus">`'s `jsonData` const is typed as
+   * Prometheus settings rather than any plugin's.
+   */
+  readonly typeArguments?: readonly string[];
   /** For `new`: the constructor's props, in source order. */
   readonly props?: Record<string, unknown>;
   /** For `value`: the value, and its type annotation with the package types it names. */

package/src/import/normalize.ts

@@ -89,6 +89,7 @@ export const VARIABLE_DEFAULTS: Readonly<Json> = {
 /** Per variable type, Grafana's value for a key the JSON leaves out, over `VARIABLE_DEFAULTS`. */
 export const VARIABLE_TYPE_DEFAULTS: Readonly<Record<string, Json>> = {
   query: { refresh: 1 },
+  adhoc: { filters: [], baseFilters: [], enableGroupBy: false },
   datasource: { refresh: 1 },
   interval: { refresh: 2, auto: false, auto_count: 30, auto_min: "10s" },
 };
@@ -264,12 +265,40 @@ function normalizeVariable(variable: unknown): unknown {
   else if (out.datasource !== undefined) out.datasource = canonicalRef(out.datasource);
   const query = typeof out.query === "string" ? out.query : undefined;
   switch (type) {
-    case "query":
-      // `definition` is the query as the editor shows it; Grafana reads `query`.
-      if (out.definition === undefined || out.definition === "" || (query !== undefined && out.definition === query)) delete out.definition;
+    case "query": {
+      // `definition` is the query as the editor shows it; Grafana reads `query` (an object query's text is its `query`).
+      const text = query ?? (isObject(out.query) && typeof out.query.query === "string" ? out.query.query : undefined);
+      if (out.definition === undefined || out.definition === "" || (text !== undefined && out.definition === text)) delete out.definition;
       // Grafana runs the query again when the dashboard loads (or the time range changes).
       if (out.refresh !== 0) delete out.options;
       break;
+    }
+    case "adhoc":
+      // The filters are the selection; Grafana reads neither of these for an ad hoc variable.
+      delete out.current;
+      delete out.options;
+      break;
+    case "groupby": {
+      // With nothing selected, Grafana starts from the default.
+      const cur = isObject(out.current) ? out.current : undefined;
+      const empty = !cur || Object.keys(cur).length === 0 || (Array.isArray(cur.value) && cur.value.length === 0);
+      if (empty || deepEqual(cur, out.defaultValue)) delete out.current;
+      if (Array.isArray(out.options) && out.options.length === 0) delete out.options;
+      // Always multi-value.
+      delete out.multi;
+      break;
+    }
+    case "switch": {
+      // Grafana reads only the values: the enabled one first, the disabled one second, and the current one.
+      const value = (o: unknown): unknown => (isObject(o) ? (Array.isArray(o.value) ? o.value[0] : o.value) : undefined);
+      const opts = Array.isArray(out.options) ? out.options : [];
+      const on = value(opts[0]) ?? "true";
+      const off = value(opts[1]) ?? "false";
+      out.options = [on, off];
+      out.current = value(out.current) ?? off;
+      delete out.query;
+      break;
+    }
     case "custom":
     case "interval": {
       const values = splitValues(query ?? "");

package/src/import/parser.test.ts

@@ -233,26 +233,84 @@ describe("variables", () => {
     expect(p.declarations.filter((d) => d.module === "variables").map((d) => d.id)[0]).toBe("variable:ds");
   });
 
-  test("a type the lexicon has no class for is reported and left out (#2952)", () => {
-    const { plan: p, warnings, edits } = plan([{ type: "adhoc", name: "Filters", datasource: prom, filters: [] }]);
+  test("a type the lexicon has no class for is reported and left out", () => {
+    const { plan: p, warnings, edits } = plan([{ type: "system", name: "__org", query: "" }]);
     expect(p.declarations.filter((d) => d.module === "variables")).toEqual([]);
-    expect(warnings).toEqual(['variable "Filters" (adhoc) is not carried: chant has no adhoc variable yet (#2952), so it is left out']);
+    expect(warnings).toEqual(['variable "__org" (system) is not carried: chant has no system variable, so it is left out']);
     expect(edits).toContainEqual({ op: "remove", path: "/templating/list/0" });
   });
 
-  test("an object query is written as its query string; keys besides refId are named", () => {
+  test("ad hoc, group by and switch variables", () => {
     const { plan: p, warnings, edits } = plan([
-      { type: "query", name: "job", datasource: prom, query: { qryType: 1, query: "label_values(job)", refId: "PrometheusVariableQueryEditor-VariableQuery" } },
+      {
+        type: "adhoc",
+        name: "Filters",
+        datasource: prom,
+        filters: [{ key: "namespace", operator: "=", value: "shop" }],
+        baseFilters: [],
+        defaultKeys: [{ text: "pod", value: "pod" }],
+        allowCustomValue: false,
+        enableGroupBy: false,
+      },
+      {
+        type: "groupby",
+        name: "by",
+        datasource: prom,
+        options: [{ text: "pod", value: "pod" }, { text: "Node", value: "node" }],
+        current: { text: ["node"], value: ["node"] },
+        defaultValue: { text: ["pod"], value: ["pod"] },
+      },
+      { type: "switch", name: "on", current: { text: "true", value: "true" }, options: [{ text: "true", value: "true" }, { text: "false", value: "false" }] },
+      { type: "switch", name: "q", current: { text: "0.5", value: "0.5" }, options: [{ text: "0.99", value: "0.99" }, { text: "0.5", value: "0.5" }] },
     ]);
-    expect(decl(p.declarations, "variable:job").props!.query).toBe("label_values(job)");
-    expect(edits).toContainEqual({ op: "replace", path: "/templating/list/0/query", value: "label_values(job)" });
-    expect(warnings).toEqual(['variable "job": query is an object; it is written as its query string, and its qryType is not carried (#2952)']);
-    expect(plan([{ type: "query", name: "j", datasource: prom, query: { query: "x", refId: "r" } }]).warnings).toEqual([]);
+    expect(warnings).toEqual([]);
+    expect(edits.filter((e) => "path" in e && e.path.startsWith("/templating"))).toEqual([]);
+    const props = (id: string) => [decl(p.declarations, id).className, decl(p.declarations, id).props];
+    expect(props("variable:Filters")).toEqual([
+      "AdhocVariable",
+      {
+        name: "Filters",
+        datasource: { $decl: "datasource:prometheus:prom" },
+        filters: [{ key: "namespace", operator: "=", value: "shop" }],
+        defaultKeys: [{ text: "pod", value: "pod" }],
+        allowCustomValue: false,
+      },
+    ]);
+    expect(props("variable:by")).toEqual([
+      "GroupByVariable",
+      {
+        name: "by",
+        datasource: { $decl: "datasource:prometheus:prom" },
+        options: ["pod", { text: "Node", value: "node" }],
+        defaultValue: ["pod"],
+        current: { text: ["node"], value: ["node"] },
+      },
+    ]);
+    expect(props("variable:on")).toEqual(["SwitchVariable", { name: "on", enabled: true }]);
+    expect(props("variable:q")).toEqual(["SwitchVariable", { name: "q", enabledValue: "0.99", disabledValue: "0.5" }]);
   });
 
-  test("an object query with no query string cannot be carried", () => {
-    const { warnings } = plan([{ type: "query", name: "ns", datasource: { type: "cloudwatch", uid: "cw" }, query: { namespace: "AWS/EC2" } }]);
-    expect(warnings).toEqual([expect.stringMatching(/^variable "ns" is not carried: its query is an object with no query string/)]);
+  test("a switch whose current value is neither of its values starts off, and says so", () => {
+    const { warnings, edits } = plan([{ type: "switch", name: "s", current: { text: "maybe", value: "maybe" }, options: [{ text: "true", value: "true" }, { text: "false", value: "false" }] }]);
+    expect(warnings).toEqual(['variable "s": current is "maybe", neither the enabled nor the disabled value; the switch starts off']);
+    expect(edits).toContainEqual({ op: "replace", path: "/templating/list/0/current", value: { text: "false", value: "false" } });
+  });
+
+  test("an ad hoc or group by variable with no datasource chant can refer to is left out", () => {
+    const { warnings } = plan([{ type: "adhoc", name: "f", datasource: { type: "prometheus" }, filters: [] }]);
+    expect(warnings).toContainEqual(expect.stringMatching(/^variable "f" is not carried: it has no datasource chant can refer to, and AdhocVariable needs one/));
+  });
+
+  test("an object query is carried as it is, with a definition that differs from its text", () => {
+    const query = { qryType: 1, query: "label_values(job)", refId: "PrometheusVariableQueryEditor-VariableQuery" };
+    const { plan: p, warnings, edits } = plan([
+      { type: "query", name: "job", datasource: prom, query, definition: "label_values(job)" },
+      { type: "query", name: "ns", datasource: { type: "cloudwatch", uid: "cw" }, query: { namespace: "AWS/EC2" }, definition: "Namespaces" },
+    ]);
+    expect(warnings).toEqual([]);
+    expect(edits.filter((e) => "path" in e && e.path.startsWith("/templating"))).toEqual([]);
+    expect(decl(p.declarations, "variable:job").props).toEqual({ name: "job", datasource: { $decl: "datasource:prometheus:prom" }, query });
+    expect(decl(p.declarations, "variable:ns").props).toMatchObject({ query: { namespace: "AWS/EC2" }, definition: "Namespaces" });
   });
 
   test("keys at Grafana's default are dropped quietly; others are named", () => {
@@ -387,26 +445,44 @@ describe("the dashboard", () => {
     expect(warnings).toContain('dashboard: uid is missing, so the dashboard is given the uid "my-board", from its title');
   });
 
-  test("the built-in annotation is Grafana's default; any other is named (#2953)", () => {
+  test("the built-in annotation is Grafana's default and left out; any other is carried (#2953)", () => {
     const builtin = { builtIn: 1, datasource: { type: "datasource", uid: "grafana" }, enable: true, hide: true, iconColor: "rgba(0, 211, 255, 1)", name: "Annotations & Alerts", type: "dashboard" };
-    expect(planDashboard(dashboard({ annotations: { list: [builtin] } })).warnings).toEqual([]);
-    const other = planDashboard(dashboard({ annotations: { list: [builtin, { name: "Deploys", enable: true }] } }));
-    expect(other.warnings).toEqual(['dashboard has the annotation "Deploys", which is not carried: Dashboard has no annotations yet (#2953)']);
-    expect(other.edits).toContainEqual({ op: "remove", path: "/annotations" });
+    const only = planDashboard(dashboard({ annotations: { list: [builtin] } }));
+    expect(only.warnings).toEqual([]);
+    expect(only.plan.declarations.find((d) => d.id === "dashboard")!.props!.annotations).toBeUndefined();
+    const deploys = { name: "Deploys", datasource: { type: "prometheus", uid: "prom" }, iconColor: "red", expr: "changes(up[5m]) > 0", step: "60s", target: { refId: "Anno" } };
+    const other = planDashboard(dashboard({ annotations: { list: [builtin, deploys, { name: "Off", enable: false, iconColor: "blue", hide: null }] } }));
+    expect(other.warnings).toEqual(['annotation "Deploys": enable is missing, so it is written as true, which runs the query']);
+    const props = other.plan.declarations.find((d) => d.id === "dashboard")!.props!;
+    expect(props.annotations).toEqual([
+      { name: "Deploys", datasource: { $decl: "datasource:prometheus:prom" }, iconColor: "red", expr: "changes(up[5m]) > 0", step: "60s", target: { refId: "Anno" } },
+      { name: "Off", enable: false, iconColor: "blue" },
+    ]);
+    expect(other.plan.declarations).toContainEqual(expect.objectContaining({ id: "datasource:prometheus:prom", className: "ExternalDatasource" }));
+    expect(other.edits).toContainEqual({ op: "replace", path: "/annotations/list/1/enable", value: true });
+    expect(other.edits).toContainEqual({ op: "remove", path: "/annotations/list/2/hide" });
   });
 });
 
 describe("provisioning files", () => {
   test("a datasource provisioning file: one Datasource each, unknown keys named", () => {
-    const ir = parse("apiVersion: 1\nprune: true\ndatasources:\n  - name: Prometheus\n    type: prometheus\n    url: http://prom:9090\n    password: x\n");
+    const ir = parse("apiVersion: 1\nprune: true\ndatasources:\n  - name: Prometheus\n    type: prometheus\n    url: http://prom:9090\n    password: x\nextra: 1\n");
     const { plan } = ir.resources[0].properties as unknown as PlanResourceProperties;
     expect(plan.declarations).toEqual([
       expect.objectContaining({ className: "Datasource", props: { name: "Prometheus", type: "prometheus", url: "http://prom:9090" } }),
     ]);
-    expect(ir.warnings).toEqual([
-      'datasource "Prometheus": password is not carried (no prop takes it)',
-      "the provisioning file: prune is not carried (chant writes datasources only; prune and deleteDatasources are #2953)",
+    expect(ir.warnings).toEqual(['datasource "Prometheus": password is not carried (no prop takes it)', "the provisioning file: extra is not carried (no prop takes it)"]);
+  });
+
+  test("a datasource provisioning file's prune and deleteDatasources become a DatasourceProvisioning (#2953)", () => {
+    const pruned = parse("apiVersion: 1\nprune: true\ndatasources: []\n").resources[0].properties as unknown as PlanResourceProperties;
+    expect(pruned.plan.declarations).toEqual([]);
+    const kept = parse("apiVersion: 1\ndeleteDatasources:\n  - name: Old\n    orgId: 2\n  - name: Gone\ndatasources: []\n");
+    const { plan } = kept.resources[0].properties as unknown as PlanResourceProperties;
+    expect(plan.declarations).toEqual([
+      expect.objectContaining({ className: "DatasourceProvisioning", props: { prune: false, deleteDatasources: [{ name: "Old", orgId: 2 }, { name: "Gone" }] } }),
     ]);
+    expect(kept.warnings).toEqual([]);
   });
 
   test("a dashboard provisioning file: file providers only", () => {