@intentius/chant-lexicon-grafana 0.99.0 → 0.100.0

package/src/build.ts

@@ -10,15 +10,28 @@
 
 import { dump } from "js-yaml";
 import type { Declarable } from "@intentius/chant/declarable";
-import { isDatasourceDeclaration, isDatasourceEntity, isExternalDatasource, type DatasourceEntity, type DatasourceRef, type ExternalDatasourceEntity } from "./datasource";
+import {
+  isDatasourceDeclaration,
+  isDatasourceEntity,
+  isDatasourceProvisioningEntity,
+  isExternalDatasource,
+  type DatasourceEntity,
+  type DatasourceProvisioningProps,
+  type DatasourceRef,
+  type DeletedDatasource,
+  type ExternalDatasourceEntity,
+} from "./datasource";
 import {
   isDashboardEntity,
   isDashboardProviderEntity,
   DEFAULT_DASHBOARDS_PATH,
   type DashboardEntity,
   type DashboardLinkInput,
-  type DashboardProviderProps,
+  type DashboardProviderEntityProps,
 } from "./dashboard";
+import { annotationJson } from "./annotations";
+import { folderLevels, isFolderEntity, type FolderEntity } from "./folder";
+import { resolveFolders, type FolderPlan } from "./api/folders";
 import { isPanelEntity, isRowEntity, type PanelEntity, type RowEntity, type PanelLink } from "./panels";
 import { isQueryEntity, type QueryEntity, type DatasourceInput } from "./query";
 import { isDatasourceVariable, isVariableEntity, type VariableEntity, type VariableHide } from "./variables";
@@ -67,6 +80,12 @@ export interface ProvisionedDatasource {
   version?: number;
 }
 
+/** The settings of the datasource provisioning file besides its datasources. */
+export interface DatasourceFileSettings {
+  prune: boolean;
+  deleteDatasources: DeletedDatasource[];
+}
+
 /** One entry of `providers:` in a dashboard provisioning file. */
 export interface ProvisionedProvider {
   name: string;
@@ -84,6 +103,8 @@ export interface BuiltDashboard {
   uid: string;
   title: string;
   folder?: string;
+  /** The uid of its folder, when it is in one. */
+  folderUid?: string;
   /** Path of its JSON file, relative to the output directory. */
   file: string;
   json: DashboardJson;
@@ -95,6 +116,10 @@ export interface BuiltGrafana {
   /** `ExternalDatasource` declarations: the checks count them, the provisioning file leaves them out. */
   externalDatasources: ExternalDatasourceRecord[];
   providers: ProvisionedProvider[];
+  /** Every folder the dashboards and `Folder`s name, each level of a path its own, sorted by path. */
+  folders: FolderPlan[];
+  /** `prune` and `deleteDatasources` of the datasource provisioning file. */
+  datasourceFile: DatasourceFileSettings;
   /** The alerting provisioning file, when the build declares any alerting. */
   alerting?: AlertingFile;
   /** Every output file by path, ready to write. */
@@ -105,7 +130,9 @@ export interface BuiltGrafana {
 
 export interface GrafanaIndex {
   grafanaSchema: string;
-  dashboards: Array<{ uid: string; title: string; folder?: string; file: string }>;
+  dashboards: Array<{ uid: string; title: string; folder?: string; folderUid?: string; file: string }>;
+  /** The folders the dashboards are in, and any `Folder` declared: what the API applier creates, parents first. */
+  folders?: FolderPlan[];
   datasources: Array<{ name: string; type: string; uid: string }>;
   /** Datasources declared with `ExternalDatasource`: referenced, never provisioned. */
   externalDatasources?: ExternalDatasourceRecord[];
@@ -215,7 +242,7 @@ export function variableModel(variable: VariableEntity): VariableModel {
         ...common,
         datasource: datasourceRef(p.datasource),
         query: p.query,
-        definition: p.query,
+        definition: p.definition ?? queryText(p.query),
         regex: p.regex,
         refresh: REFRESH[(p.refresh ?? "onLoad") as keyof typeof REFRESH],
         sort: p.sort,
@@ -274,9 +301,51 @@ export function variableModel(variable: VariableEntity): VariableModel {
         query: p.value ?? "",
         current: { text: p.value ?? "", value: p.value ?? "" },
       }) as VariableModel;
+    case "adhoc":
+      return compact({
+        ...common,
+        datasource: datasourceRef(p.datasource),
+        filters: p.filters ?? [],
+        baseFilters: p.baseFilters ?? [],
+        defaultKeys: p.defaultKeys,
+        allowCustomValue: p.allowCustomValue,
+        enableGroupBy: p.enableGroupBy,
+      }) as VariableModel;
+    case "groupby": {
+      const options = p.options?.map((o: string | { text: string; value: string }) => (typeof o === "string" ? { text: o, value: o } : o));
+      const defaultValue = Array.isArray(p.defaultValue) ? { text: p.defaultValue, value: p.defaultValue } : p.defaultValue;
+      return compact({
+        ...common,
+        datasource: datasourceRef(p.datasource),
+        options,
+        current: p.current ?? defaultValue,
+        defaultValue,
+        allowCustomValue: p.allowCustomValue,
+      }) as VariableModel;
+    }
+    case "switch": {
+      const on: string = p.enabledValue ?? "true";
+      const off: string = p.disabledValue ?? "false";
+      const value = p.enabled ? on : off;
+      return compact({
+        ...common,
+        current: { text: value, value },
+        options: [
+          { text: on, value: on },
+          { text: off, value: off },
+        ],
+      }) as VariableModel;
+    }
   }
 }
 
+/** The text of a variable query: the string, or an object query's `query`. */
+function queryText(query: unknown): string | undefined {
+  if (typeof query === "string") return query;
+  if (query && typeof query === "object" && typeof (query as { query?: unknown }).query === "string") return (query as { query: string }).query;
+  return undefined;
+}
+
 // ── Panels and layout ───────────────────────────────────────────
 
 function repeatName(repeat: VariableEntity | string | undefined): string | undefined {
@@ -531,7 +600,7 @@ export function dashboardUid(dashboard: DashboardEntity, exportName?: string): s
 export function renderDashboard(dashboard: DashboardEntity, exportName?: string): DashboardJson {
   const p = dashboard.props;
   return compact({
-    annotations: { list: [] },
+    annotations: { list: (p.annotations ?? []).map((a) => annotationJson(a, datasourceRef)) },
     description: p.description,
     editable: p.editable ?? true,
     fiscalYearStartMonth: p.fiscalYearStartMonth ?? 0,
@@ -598,7 +667,7 @@ export function externalDatasourceRecord(ds: ExternalDatasourceEntity): External
 }
 
 /** One dashboard provider as a provisioning entry. */
-export function provisionedProvider(p: DashboardProviderProps): ProvisionedProvider {
+export function provisionedProvider(p: DashboardProviderEntityProps): ProvisionedProvider {
   const pinnedFolder = p.folder !== undefined || p.folderUid !== undefined;
   return compact({
     name: p.name,
@@ -620,9 +689,26 @@ function yamlFile(header: string, body: Record<string, unknown>): string {
   return `# ${header}\n${dump(body, { lineWidth: -1, noRefs: true, quotingType: '"' })}`;
 }
 
-/** The datasource provisioning file for these datasources. */
-export function datasourcesYaml(datasources: ProvisionedDatasource[]): string {
-  return yamlFile("Grafana datasource provisioning, generated by chant.", { apiVersion: 1, datasources });
+/** `prune` and `deleteDatasources` as a build writes them: pruning on unless a `DatasourceProvisioning` turns it off. */
+export function datasourceFileSettings(props: DatasourceProvisioningProps | undefined): DatasourceFileSettings {
+  return {
+    prune: props?.prune ?? true,
+    deleteDatasources: (props?.deleteDatasources ?? []).map((d) => ({ name: d.name, ...(d.orgId !== undefined ? { orgId: d.orgId } : {}) })),
+  };
+}
+
+/**
+ * The datasource provisioning file for these datasources. It prunes by
+ * default (`prune: true`), so a datasource removed from the build is removed
+ * from Grafana; `deleteDatasources` comes first, as Grafana runs it first.
+ */
+export function datasourcesYaml(datasources: ProvisionedDatasource[], settings: DatasourceFileSettings = datasourceFileSettings(undefined)): string {
+  return yamlFile("Grafana datasource provisioning, generated by chant.", {
+    apiVersion: 1,
+    ...(settings.prune ? { prune: true } : {}),
+    ...(settings.deleteDatasources.length > 0 ? { deleteDatasources: settings.deleteDatasources } : {}),
+    datasources,
+  });
 }
 
 /** The dashboard provisioning file for these providers. */
@@ -632,19 +718,18 @@ export function dashboardProvidersYaml(providers: ProvisionedProvider[]): string
 
 /**
  * A dashboard's `folder` as its directory under `dashboards/`: one
- * subdirectory per `/`-separated level, which a provider with
+ * subdirectory per level (`folderLevels`), which a provider with
  * `foldersFromFilesStructure` turns into nested folders on Grafana 13.1 and
- * later (GRAF109 says what earlier versions do). Leading dots and blank
- * levels are dropped, so a folder can't name a directory outside
- * `dashboards/`; a backslash becomes `-`. Empty when nothing is left: the
- * General folder.
+ * later (GRAF109 says what earlier versions do). Empty for the General
+ * folder.
  */
 function folderDir(folder: string): string {
-  return folder
-    .split("/")
-    .map((level) => level.replace(/\\+/g, "-").trim().replace(/^\.+/, "").trim())
-    .filter((level) => level !== "")
-    .join("/");
+  return folderLevels(folder).join("/");
+}
+
+/** A `Folder` and every folder above it. */
+function withAncestors(folder: FolderEntity, into: Set<FolderEntity>): void {
+  for (let f: FolderEntity | undefined = folder; f; f = f.props.parent) into.add(f);
 }
 
 // ── The whole build ─────────────────────────────────────────────
@@ -666,6 +751,17 @@ export function buildGrafana(entities: Map<string, Declarable> | Iterable<Declar
     .map(([, e]) => externalDatasourceRecord(e as ExternalDatasourceEntity))
     .sort((a, b) => a.uid.localeCompare(b.uid));
 
+  // Folders: every declared `Folder` and every one a dashboard holds, with their parents, pin uids; every path a dashboard names is a folder per level.
+  const declaredFolders = new Set<FolderEntity>();
+  for (const [, e] of named) {
+    if (isFolderEntity(e)) withAncestors(e, declaredFolders);
+    else if (isDashboardEntity(e) && e.folderEntity) withAncestors(e.folderEntity, declaredFolders);
+  }
+  const resolved = resolveFolders({
+    declared: [...declaredFolders].map((f) => ({ uid: f.uid, path: f.path })),
+    paths: named.flatMap(([, e]) => (isDashboardEntity(e) && e.props.folder ? [e.props.folder] : [])),
+  }, { duplicateUids: "keep" });
+
   const dashboards: BuiltDashboard[] = [];
   for (const [name, e] of named) {
     if (!isDashboardEntity(e)) continue;
@@ -677,10 +773,15 @@ export function buildGrafana(entities: Map<string, Declarable> | Iterable<Declar
     let file = `${dir}/${uid}.json`;
     for (let n = 2; file in files; n++) file = `${dir}/${uid}-${n}.json`;
     files[file] = `${JSON.stringify(json, null, 2)}\n`;
-    dashboards.push({ uid, title: e.props.title, ...(folder ? { folder } : {}), file, json });
+    const folderUid = sub ? resolved.uidOf(sub) : undefined;
+    dashboards.push({ uid, title: e.props.title, ...(folder ? { folder } : {}), ...(folderUid ? { folderUid } : {}), file, json });
   }
 
-  const declaredProviders = named.filter(([, e]) => isDashboardProviderEntity(e)).map(([, e]) => (e as unknown as { props: DashboardProviderProps }).props);
+  const settings = named.map(([, e]) => e).filter(isDatasourceProvisioningEntity);
+  if (settings.length > 1) throw new Error("grafana: declare at most one DatasourceProvisioning; the build writes one datasource provisioning file");
+  const datasourceFile = datasourceFileSettings(settings[0]?.props);
+
+  const declaredProviders = named.filter(([, e]) => isDashboardProviderEntity(e)).map(([, e]) => (e as unknown as { props: DashboardProviderEntityProps }).props);
   const providers =
     declaredProviders.length > 0
       ? declaredProviders.map(provisionedProvider)
@@ -688,20 +789,21 @@ export function buildGrafana(entities: Map<string, Declarable> | Iterable<Declar
         ? [provisionedProvider({ name: DEFAULT_PROVIDER_NAME })]
         : [];
 
-  if (datasources.length > 0) files[DATASOURCES_FILE] = datasourcesYaml(datasources);
+  if (datasources.length > 0 || datasourceFile.deleteDatasources.length > 0) files[DATASOURCES_FILE] = datasourcesYaml(datasources, datasourceFile);
   if (providers.length > 0) files[DASHBOARD_PROVIDERS_FILE] = dashboardProvidersYaml(providers);
   const alerting = buildAlerting(named.map(([, e]) => e));
   if (alerting) files[ALERTING_FILE] = alertingYaml(alerting.file);
 
   const index: GrafanaIndex = {
     grafanaSchema: `${GRAFANA_SCHEMA_PIN.source}@${GRAFANA_SCHEMA_PIN.ref}`,
-    dashboards: dashboards.map(({ uid, title, folder, file }) => ({ uid, title, ...(folder ? { folder } : {}), file })),
+    dashboards: dashboards.map(({ uid, title, folder, folderUid, file }) => ({ uid, title, ...(folder ? { folder } : {}), ...(folderUid ? { folderUid } : {}), file })),
+    ...(resolved.folders.length > 0 ? { folders: resolved.folders } : {}),
     datasources: datasources.map(({ name, type, uid }) => ({ name, type, uid })),
     ...(externalDatasources.length > 0 ? { externalDatasources } : {}),
     ...(alerting ? { alerting: alerting.index } : {}),
     files: Object.keys(files).sort(),
   };
-  return { dashboards, datasources, externalDatasources, providers, ...(alerting ? { alerting: alerting.file } : {}), files, index };
+  return { dashboards, datasources, externalDatasources, providers, folders: resolved.folders, datasourceFile, ...(alerting ? { alerting: alerting.file } : {}), files, index };
 }
 
 /** Every file the grafana entities render to, by path relative to the output directory. */

package/src/catalog.ts

@@ -5,7 +5,8 @@
  */
 
 import type { LexiconEntry } from "@intentius/chant/lsp/lexicon-providers";
-import { DATASOURCE_TYPE, EXTERNAL_DATASOURCE_TYPE } from "./datasource";
+import { DATASOURCE_PROVISIONING_TYPE, DATASOURCE_TYPE, EXTERNAL_DATASOURCE_TYPE } from "./datasource";
+import { FOLDER_TYPE } from "./folder";
 import { DASHBOARD_TYPE, DASHBOARD_PROVIDER_TYPE } from "./dashboard";
 import * as panels from "./panels";
 import * as queries from "./query";
@@ -21,7 +22,7 @@ import {
   NOTIFICATION_TEMPLATE_TYPE,
 } from "./alerting";
 
-export type CatalogKind = "dashboard" | "datasource" | "provider" | "panel" | "row" | "query" | "variable" | "alerting" | "expression";
+export type CatalogKind = "dashboard" | "folder" | "datasource" | "provider" | "panel" | "row" | "query" | "variable" | "alerting" | "expression";
 
 export interface CatalogEntry {
   className: string;
@@ -67,6 +68,9 @@ const VARIABLES: Array<[string, string, string]> = [
   ["DatasourceVariable", "datasource", "A choice of datasource of one plugin type; usable wherever a datasource is"],
   ["ConstantVariable", "constant", "A hidden, fixed value"],
   ["TextboxVariable", "textbox", "A free-text box"],
+  ["AdhocVariable", "adhoc", "Key/value filters Grafana adds to every query sent to the variable's datasource"],
+  ["GroupByVariable", "groupby", "A choice of label keys Grafana groups every query to the variable's datasource by (experimental in Grafana)"],
+  ["SwitchVariable", "switch", "An on/off switch with a value for each state (Grafana 12.3 and later)"],
 ];
 
 const EXPRESSIONS: Array<[string, string, string]> = [
@@ -100,6 +104,20 @@ export const BUILTIN_CATALOG: CatalogEntry[] = [
     entityKind: "resource",
     description: "A datasource that already exists in Grafana: referenced like a Datasource and checked by GRAF101/GRAF102, never provisioned",
   },
+  {
+    className: "Folder",
+    entityType: FOLDER_TYPE,
+    kind: "folder",
+    entityKind: "resource",
+    description: "A folder with a stable uid, nested with parent; a dashboard's folder may be one instead of a path",
+  },
+  {
+    className: "DatasourceProvisioning",
+    entityType: DATASOURCE_PROVISIONING_TYPE,
+    kind: "provider",
+    entityKind: "resource",
+    description: "The datasource provisioning file's prune (on by default) and deleteDatasources",
+  },
   {
     className: "DashboardProvider",
     entityType: DASHBOARD_PROVIDER_TYPE,

package/src/codegen/docs.ts

@@ -31,10 +31,17 @@ export const overview = new Dashboard({ title: "Overview", panels: [requests] })
 
 Panels: time series, stat, gauge, table, logs, traces, heatmap, text, bar
 chart, bar gauge, pie chart, state timeline, status history, histogram, node
-graph, XY chart, trend, canvas, geomap, flame graph and alert list, plus rows. Queries: Prometheus (PromQL), Tempo (TraceQL) and Loki (LogQL). Panel
-options and query fields are generated from Grafana's own schemas at a pinned
-version, corrected against Grafana's CUE, and track Grafana 12.4 and 13.x. Every
-build validates the dashboards against the same schemas.
+graph, XY chart, trend, canvas, geomap, flame graph and alert list, plus rows.
+Queries: Prometheus (PromQL), Tempo (TraceQL), Loki (LogQL), Elasticsearch,
+CloudWatch, Azure Monitor, Cloud Monitoring, BigQuery, Pyroscope, and SQL for
+PostgreSQL, MySQL and MSSQL. Panel options and query fields are generated from
+Grafana's own schemas at a pinned version, corrected against Grafana's CUE, and
+track Grafana 12.4 and 13.x. Every build validates the dashboards against the
+same schemas.
+Dashboards are written in the classic (v1) JSON model. Grafana 13's v2 model
+(tabs, auto grids, conditional rendering) cannot be declared yet; import and
+drift read a v2 dashboard by converting it to the classic model, and say what
+the conversion loses.
 \`definePanel\` and \`defineQuery\` add plugins chant doesn't ship.
 \`chant import\` turns dashboard JSON exported from Grafana into this TypeScript,
 and it builds back to the same dashboard (see
@@ -65,8 +72,8 @@ wrong type (GRAF102), a \`$variable\` the dashboard doesn't declare (GRAF103),
 duplicate uids and ids (GRAF104), panels off the grid or overlapping (GRAF105),
 anything Grafana's dashboard schema rejects (GRAF107), PromQL sent to a
 Prometheus that doesn't parse (GRAF108), dashboard providers that load a
-dashboard twice or not into its declared folder (GRAF109), and a unit Grafana
-doesn't know (GRAF115). For alerting, they catch rules whose condition or expressions name
+dashboard twice or not into its declared folder (GRAF109), a panel repeated over a variable that only ever
+holds one value (GRAF110), and a unit Grafana doesn't know (GRAF115). For alerting, they catch rules whose condition or expressions name
 no query (GRAF111), queries to undeclared datasources (GRAF112), routes to
 undeclared contact points or mute timings (GRAF113), and uids, intervals and
 duplicates Grafana refuses (GRAF114).

package/src/codegen/generate.ts

@@ -4,7 +4,11 @@
  * 1. `src/schema/<name>.gen.ts` from each vendored schema in `src/spec/schemas/`
  *    (see `src/pin.ts`). These are committed, and a test fails when they
  *    drift from what this step would write.
- * 2. `src/generated/lexicon-grafana.json`, the registry of entity classes
+ * 2. `src/spec/schemas.gen.ts`, the same schemas with the overlay applied, as
+ *    JSON text. Validation (GRAF107, the `/validation` subpath) reads them
+ *    from there rather than from the files, so it needs no filesystem access
+ *    and works bundled. Committed and checked the same way.
+ * 3. `src/generated/lexicon-grafana.json`, the registry of entity classes
  *    the package exports, derived from the catalog so the packaged
  *    `dist/meta.json` cannot disagree with the classes.
  */
@@ -29,6 +33,27 @@ function dashboardExtras(schema: Record<string, unknown>): string[] {
   return ["/** The dashboard `schemaVersion` the pinned schema defaults to, and the one chant emits. */", `export const DASHBOARD_SCHEMA_VERSION = ${v};`];
 }
 
+/** `src/spec/schemas.gen.ts`: each schema validation uses, overlay applied, as one line of JSON text. */
+export function schemaDataModule(): string {
+  const lines = [
+    "// Code generated by chant generate. DO NOT EDIT.",
+    "// The vendored Grafana schemas (src/spec/schemas/, see src/pin.ts) with the",
+    "// correction overlay (src/spec/overlay/) applied, as JSON text, for",
+    "// src/schema-validate.ts. A module rather than a file read, so validation",
+    "// needs no filesystem access and survives bundling; text rather than object",
+    "// literals, so loading it costs little until a schema is parsed.",
+    "",
+    'import type { SchemaName } from "../pin";',
+    "",
+    "export const SCHEMA_JSON: Readonly<Record<SchemaName, string>> = {",
+  ];
+  for (const name of SCHEMA_NAMES) {
+    lines.push(`  ${JSON.stringify(name)}: ${JSON.stringify(JSON.stringify(loadSchema(name as SchemaName)))},`);
+  }
+  lines.push("};", "");
+  return lines.join("\n");
+}
+
 /** Every generated schema module, keyed by path relative to the package root. */
 export function schemaModules(): Record<string, string> {
   const out: Record<string, string> = {};
@@ -37,6 +62,7 @@ export function schemaModules(): Record<string, string> {
     const extra = name === "dashboard" ? dashboardExtras(schema) : [];
     out[`src/schema/${name}.gen.ts`] = schemaModule(name, schema, extra).source;
   }
+  out["src/spec/schemas.gen.ts"] = schemaDataModule();
   return out;
 }
 

package/src/composites/shared.ts

@@ -5,6 +5,7 @@
 
 import type { DatasourceInput } from "../query";
 import type { DashboardLinkInput } from "../dashboard";
+import type { FolderEntity } from "../folder";
 import type { ThresholdsConfig } from "../schema/dashboard.gen";
 
 /** Dashboard settings every composite takes; each has a default derived from what it reads. */
@@ -16,8 +17,8 @@ export interface DashboardOptions {
   uid?: string;
   description?: string;
   tags?: string[];
-  /** The Grafana folder to provision it into. */
-  folder?: string;
+  /** The Grafana folder to provision it into: a path, or a `Folder` to pin its uid. */
+  folder?: string | FolderEntity;
   /** Initial time range. */
   time?: { from: string; to: string };
   /** Auto-refresh interval, e.g. `30s`. */

package/src/dashboard.ts

@@ -12,6 +12,8 @@ import type { Declarable } from "@intentius/chant/declarable";
 import type { PanelEntity, RowEntity } from "./panels";
 import type { VariableEntity } from "./variables";
 import type { DashboardLink, TimePickerConfig } from "./schema/dashboard.gen";
+import { isFolderEntity, type FolderEntity } from "./folder";
+import type { AnnotationInput } from "./annotations";
 
 /** A dashboard link: `title` and `type` required, the rest defaulted as Grafana's editor would. */
 export type DashboardLinkInput = Partial<DashboardLink> & Pick<DashboardLink, "title" | "type">;
@@ -54,26 +56,50 @@ export interface DashboardProps {
   panels?: Array<PanelEntity<any, any> | RowEntity>;
   links?: DashboardLinkInput[];
   /**
-   * The Grafana folder to provision it into. Written as a subdirectory of
-   * `dashboards/`, which the provider maps to folders
-   * (`foldersFromFilesStructure`). `"Platform/Kubernetes"` nests one
-   * directory in another, which Grafana 13.1 and later make a Kubernetes
-   * folder inside Platform; earlier versions use only the last level
-   * (GRAF109 warns). Leave it out for the General folder.
+   * Annotation queries: events drawn on the dashboard's time series panels
+   * (deploys, incidents), each from a datasource. Grafana adds its own
+   * "Annotations & Alerts" query to every dashboard that has none with
+   * `builtIn: 1`, so leave that one out unless you change it.
    */
-  folder?: string;
+  annotations?: AnnotationInput[];
+  /**
+   * The Grafana folder: a path (`"Platform/Kubernetes"`) or a `Folder`,
+   * which pins the folder's uid. Written as a subdirectory of `dashboards/`,
+   * which the provider maps to folders (`foldersFromFilesStructure`); a path
+   * nests one directory in another, which Grafana 13.1 and later make a
+   * Kubernetes folder inside Platform, and earlier versions use only the
+   * last level (GRAF109 warns). The API applier creates each level with its
+   * uid. Leave it out for the General folder.
+   */
+  folder?: string | FolderEntity;
 }
 
+/** A dashboard's props as the entity holds them: `folder` is always the path, and a `Folder` given for it is `folderEntity`. */
+export type DashboardEntityProps = Omit<DashboardProps, "folder"> & { folder?: string };
+
 export interface DashboardEntity extends Declarable {
-  readonly props: DashboardProps;
+  readonly props: DashboardEntityProps;
+  /** The `Folder` the dashboard was given, when it was given one rather than a path. */
+  readonly folderEntity?: FolderEntity;
 }
 
 export const DASHBOARD_TYPE = "Grafana::Dashboard";
 
 const DashboardBase = createResource(DASHBOARD_TYPE, "grafana", {}) as unknown as (this: object, props: Record<string, unknown>) => void;
 
-/** A Grafana dashboard. */
+/**
+ * A Grafana dashboard. A `Folder` given as its `folder` is held as the
+ * folder's path, so everything that reads the dashboard's props (the build,
+ * the checks, observation's diff) sees one form; the `Folder` itself, for its
+ * uid, is `folderEntity`.
+ */
 export const Dashboard = function (this: object, props: DashboardProps) {
+  const folder = props.folder;
+  if (isFolderEntity(folder)) {
+    DashboardBase.call(this, { ...props, folder: folder.path } as unknown as Record<string, unknown>);
+    Object.defineProperty(this, "folderEntity", { value: folder, enumerable: false });
+    return;
+  }
   DashboardBase.call(this, props as unknown as Record<string, unknown>);
 } as unknown as new (props: DashboardProps) => DashboardEntity;
 Object.defineProperty(Dashboard, "name", { value: "Dashboard" });
@@ -95,11 +121,14 @@ export interface DashboardProviderProps {
   name: string;
   orgId?: number;
   /**
-   * Put every dashboard this provider loads in this folder. Setting it (or
-   * `folderUid`) turns `foldersFromFilesStructure` off by default, so each
-   * dashboard's own `folder` is ignored (GRAF109 warns).
+   * Put every dashboard this provider loads in this folder: a title, or a
+   * root-level `Folder`, whose title and uid are written as `folder` and
+   * `folderUid` (Grafana creates a provider's folder at the root, so a
+   * nested `Folder` is refused). Setting it (or `folderUid`) turns
+   * `foldersFromFilesStructure` off by default, so each dashboard's own
+   * `folder` is ignored (GRAF109 warns).
    */
-  folder?: string;
+  folder?: string | FolderEntity;
   folderUid?: string;
   /** Where the `dashboards/` output is mounted in the Grafana container. Defaults to `/var/lib/grafana/dashboards`. */
   path?: string;
@@ -110,8 +139,11 @@ export interface DashboardProviderProps {
   updateIntervalSeconds?: number;
 }
 
+/** A provider's props as the entity holds them: a `Folder` given for `folder` is written out as `folder` and `folderUid`. */
+export type DashboardProviderEntityProps = Omit<DashboardProviderProps, "folder"> & { folder?: string };
+
 export interface DashboardProviderEntity extends Declarable {
-  readonly props: DashboardProviderProps;
+  readonly props: DashboardProviderEntityProps;
 }
 
 export const DASHBOARD_PROVIDER_TYPE = "Grafana::DashboardProvider";
@@ -123,6 +155,19 @@ const ProviderBase = createResource(DASHBOARD_PROVIDER_TYPE, "grafana", {}) as u
 
 /** An entry in the dashboard provisioning file. Optional: a default one is written when none is declared. */
 export const DashboardProvider = function (this: object, props: DashboardProviderProps) {
+  const folder = props.folder;
+  if (isFolderEntity(folder)) {
+    if (folder.props.parent) {
+      throw new Error(
+        `grafana: DashboardProvider "${props.name}" puts its dashboards in the Folder "${folder.path}", which is nested; Grafana creates a provider's folder at the root. Give it a root-level Folder, or leave folder out and set each dashboard's folder`,
+      );
+    }
+    if (props.folderUid !== undefined && props.folderUid !== folder.uid) {
+      throw new Error(`grafana: DashboardProvider "${props.name}" has folderUid "${props.folderUid}", but its Folder's uid is "${folder.uid}"`);
+    }
+    ProviderBase.call(this, { ...props, folder: folder.props.title, folderUid: folder.uid } as unknown as Record<string, unknown>);
+    return;
+  }
   ProviderBase.call(this, props as unknown as Record<string, unknown>);
 } as unknown as new (props: DashboardProviderProps) => DashboardProviderEntity;
 Object.defineProperty(DashboardProvider, "name", { value: "DashboardProvider" });

package/src/datasource-refs.ts

@@ -48,14 +48,15 @@ export type ResolvedDatasource =
 
 /** One place a dashboard names, or inherits, a datasource. */
 export interface DatasourceUse {
-  /** A panel's own `datasource`, one of its queries (`targets`), or a query variable. */
-  kind: "panel" | "query" | "variable";
+  /** A panel's own `datasource`, one of its queries (`targets`), a query, ad hoc or group by variable, or an annotation query. */
+  kind: "panel" | "query" | "variable" | "annotation";
   /** A human description, e.g. `panel "Latency" (id 3) query B`. */
   where: string;
   panel?: Json;
   target?: Json;
   variable?: Json;
-  /** The ref written on this panel, query or variable; unset when a query inherits its panel's. */
+  annotation?: Json;
+  /** The ref written on this panel, query, variable or annotation; unset when a query inherits its panel's. */
   ref?: DatasourceRefJson;
   /** Where the request goes: the query's own ref, else its panel's. */
   resolved: ResolvedDatasource;
@@ -146,10 +147,20 @@ export function resolveDatasourceRef(
   return { kind: "undeclared", uid: ref.uid, ...(ref.type ? { type: ref.type } : {}) };
 }
 
+/** Variable types that send requests to a datasource of their own: a query variable's query, an ad hoc or group by variable's key and value lookups. */
+const DATASOURCE_VARIABLE_TYPES: ReadonlySet<string> = new Set(["query", "adhoc", "groupby"]);
+
+/** A dashboard's `annotations.list`. */
+export function annotationsOf(dashboard: Json): Json[] {
+  const list = (dashboard.annotations as { list?: unknown } | undefined)?.list;
+  return Array.isArray(list) ? (list as Json[]).filter((a) => a && typeof a === "object" && !Array.isArray(a)) : [];
+}
+
 /**
  * Every place a dashboard names or inherits a datasource: each panel's own
- * ref, each query (with its own ref, or its panel's when it has none), and
- * each query variable. Rows are left out; their panels carry the ref.
+ * ref, each query (with its own ref, or its panel's when it has none), each
+ * query, ad hoc and group by variable, and each annotation query with a datasource. Rows are left
+ * out; their panels carry the ref.
  */
 export function datasourceUses(dashboard: Json, known: ReadonlyMap<string, KnownDatasource>): DatasourceUse[] {
   const dsVars = datasourceVariables(dashboard);
@@ -175,7 +186,7 @@ export function datasourceUses(dashboard: Json, known: ReadonlyMap<string, Known
     }
   }
   for (const variable of variablesOf(dashboard)) {
-    if (variable.type !== "query") continue;
+    if (!DATASOURCE_VARIABLE_TYPES.has(String(variable.type))) continue;
     const ref = refOf(variable.datasource);
     out.push({
       kind: "variable",
@@ -185,5 +196,18 @@ export function datasourceUses(dashboard: Json, known: ReadonlyMap<string, Known
       resolved: resolveDatasourceRef(ref, dsVars, known),
     });
   }
+  for (const annotation of annotationsOf(dashboard)) {
+    const ref = refOf(annotation.datasource);
+    if (!ref) continue;
+    const target = refOf(annotation.target) as Json | undefined;
+    out.push({
+      kind: "annotation",
+      where: `annotation "${String(annotation.name ?? "?")}"`,
+      annotation,
+      ...(target ? { target } : {}),
+      ref,
+      resolved: resolveDatasourceRef(ref, dsVars, known),
+    });
+  }
   return out;
 }