@intentius/chant-lexicon-grafana 0.98.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 { isDatasourceEntity, type DatasourceEntity, type DatasourceRef } 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";
@@ -34,6 +47,8 @@ import type {
 import { DASHBOARD_SCHEMA_VERSION } from "./schema/dashboard.gen";
 import { GRAFANA_SCHEMA_PIN } from "./pin";
 import { compact, slugUid } from "./util";
+import { ALERTING_FILE, alertingYaml, buildAlerting, type AlertingFile, type AlertingIndex } from "./alerting-build";
+import { DEFAULT_PROVIDER_NAME } from "./ownership";
 
 export type { DashboardJson, PanelJson, RowPanelJson, VariableModel, DataSourceRef };
 
@@ -65,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;
@@ -82,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;
@@ -90,7 +113,15 @@ export interface BuiltDashboard {
 export interface BuiltGrafana {
   dashboards: BuiltDashboard[];
   datasources: ProvisionedDatasource[];
+  /** `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. */
   files: Record<string, string>;
   /** A short summary of what was built: the serializer's primary output. */
@@ -99,11 +130,24 @@ 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[];
+  /** Rule groups, contact points, policies, mute timings and templates, when the build declares any. */
+  alerting?: AlertingIndex;
   files: string[];
 }
 
+/** An `ExternalDatasource` as the checks and the index see it. */
+export interface ExternalDatasourceRecord {
+  type: string;
+  uid: string;
+  name?: string;
+}
+
 // ── References ──────────────────────────────────────────────────
 
 function isRef(value: unknown): value is DatasourceRef {
@@ -116,13 +160,13 @@ function isRef(value: unknown): value is DatasourceRef {
   );
 }
 
-/** The `{ type, uid }` Grafana stores for a datasource, a datasource variable, or a ref. */
+/** The `{ type, uid }` Grafana stores for a datasource (declared or external), a datasource variable, or a ref. */
 export function datasourceRef(input: DatasourceInput | undefined): DataSourceRef | undefined {
   if (input === undefined || input === null) return undefined;
-  if (isDatasourceEntity(input)) return { type: input.datasourceType, uid: input.uid };
+  if (isDatasourceDeclaration(input)) return { type: input.datasourceType, uid: input.uid };
   if (isDatasourceVariable(input)) return { type: input.pluginType, uid: `\${${input.variableName}}` };
   if (isRef(input)) return { type: input.type, uid: input.uid };
-  throw new Error("grafana: a datasource must be a Datasource, a DatasourceVariable or a { type, uid } ref");
+  throw new Error("grafana: a datasource must be a Datasource, an ExternalDatasource, a DatasourceVariable or a { type, uid } ref");
 }
 
 function sameRef(a: DataSourceRef | undefined, b: DataSourceRef | undefined): boolean {
@@ -154,8 +198,24 @@ function dashboardLink(link: DashboardLinkInput | PanelLink): DashboardLink {
 const HIDE: Record<VariableHide, 0 | 1 | 2> = { label: 0, valueOnly: 1, hidden: 2 };
 const REFRESH = { never: 0, onLoad: 1, onTimeRangeChange: 2 } as const;
 
+/** A custom variable value in its `query`: a comma is escaped as `\\,`, and one already escaped is left alone. */
 function escapeCustom(v: string): string {
-  return v.replace(/,/g, "\\,");
+  return v.replace(/\\?,/g, "\\,");
+}
+
+/**
+ * The options Grafana makes of a custom variable's `query`: split on commas
+ * not escaped as `\\,`, and `text : value` (spaces around the colon) read as
+ * an option showing `text` that sets `value`. The same parse as Grafana's
+ * custom variable (public/app/features/variables/custom/reducer.ts, and
+ * CustomVariable in @grafana/scenes).
+ */
+export function customVariableOptions(query: string): Array<{ text: string; value: string }> {
+  return (query.match(/(?:\\,|[^,])+/g) ?? []).map((item) => {
+    const text = item.replace(/\\,/g, ",");
+    const kv = /^\s*(.+)\s:\s(.+)$/.exec(text);
+    return kv ? { text: kv[1].trim(), value: kv[2].trim() } : { text: text.trim(), value: text.trim() };
+  });
 }
 
 function optionsOf(values: string[], current?: { text: string | string[]; value: string | string[] }) {
@@ -182,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,
@@ -192,13 +252,16 @@ export function variableModel(variable: VariableEntity): VariableModel {
       }) as VariableModel;
     case "custom": {
       const values: string[] = p.values;
-      const current = p.current ?? (values[0] !== undefined ? { text: values[0], value: values[0] } : undefined);
+      const query = values.map(escapeCustom).join(",");
+      const options = customVariableOptions(query);
+      const current = p.current ?? (options[0] !== undefined ? { text: options[0].text, value: options[0].value } : undefined);
+      const selected = current ? (Array.isArray(current.value) ? current.value : [current.value]) : [];
       return compact({
         ...common,
-        query: values.map(escapeCustom).join(","),
+        query,
         ...multi,
         current,
-        options: optionsOf(values, current),
+        options: options.map((o) => ({ selected: selected.includes(o.value), ...o })),
       }) as VariableModel;
     }
     case "interval": {
@@ -238,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 {
@@ -266,47 +371,110 @@ export function targetJson(query: QueryEntity, index: number, panelDatasource?:
   });
 }
 
+/** A bitmask of grid columns [x, x + w), clipped to the grid. */
+function columns(x: number, w: number): number {
+  const from = Math.max(0, x);
+  const to = Math.min(GRID_COLUMNS, x + w);
+  return to > from ? ((1 << (to - from)) - 1) << from : 0;
+}
+
+/**
+ * Places panels on Grafana's grid. It keeps an occupancy grid, so a panel
+ * placed automatically never lands on one placed explicitly (reserved up
+ * front) or on one placed before it.
+ */
 class Layout {
   private x = 0;
-  private y = 0;
+  private y: number;
   private lineH = 0;
-  private bottom = 0;
+  private bottom: number;
+  /** Taken cells: one column bitmask per grid line. */
+  private readonly taken: number[] = [];
+
+  constructor(top = 0) {
+    this.y = top;
+    this.bottom = top;
+  }
+
+  /** Marks the cells of a panel with both `x` and `y` as taken, before anything is placed. */
+  reserve(gp: Partial<GridPos> | undefined, size: { w: number; h: number }): void {
+    if (gp?.x === undefined || gp?.y === undefined) return;
+    this.take(gp.x, gp.y, gp.w ?? size.w, gp.h ?? size.h);
+  }
 
   place(gp: Partial<GridPos> | undefined, size: { w: number; h: number }): GridPos {
     const w = gp?.w ?? size.w;
     const h = gp?.h ?? size.h;
     if (gp?.x !== undefined && gp?.y !== undefined) {
+      this.take(gp.x, gp.y, w, h);
       this.bottom = Math.max(this.bottom, gp.y + h);
       return { h, w, x: gp.x, y: gp.y };
     }
-    if (this.x + w > GRID_COLUMNS && this.x > 0) {
-      this.y += this.lineH;
+    if (gp?.y !== undefined) {
+      // Only `y`: the first free column on that line, else on the first line below with room.
+      for (let y = Math.max(0, gp.y); ; y++) {
+        const x = this.freeColumn(0, y, w, h);
+        if (x === undefined) continue;
+        this.take(x, y, w, h);
+        this.bottom = Math.max(this.bottom, y + h);
+        return { h, w, x, y };
+      }
+    }
+    // Flow: the first free spot on the current line after the previous panel, else the next line.
+    // Only `x`: that column, on the first line where it is free.
+    for (;;) {
+      const x =
+        gp?.x === undefined
+          ? this.freeColumn(this.x, this.y, w, h)
+          : gp.x >= this.x && this.free(gp.x, this.y, w, h)
+            ? gp.x
+            : undefined;
+      if (x !== undefined) {
+        const pos = { h, w, x, y: this.y };
+        this.take(x, this.y, w, h);
+        this.x = x + w;
+        this.lineH = Math.max(this.lineH, h);
+        this.bottom = Math.max(this.bottom, this.y + h);
+        return pos;
+      }
+      this.y += this.lineH || 1;
       this.x = 0;
       this.lineH = 0;
     }
-    const pos = { h, w, x: this.x, y: this.y };
-    this.x += w;
-    this.lineH = Math.max(this.lineH, h);
-    this.bottom = Math.max(this.bottom, this.y + h);
-    return pos;
   }
 
-  /** A full-width row header below everything placed so far. */
-  row(): { pos: GridPos; mark: () => void } {
-    const y = Math.max(this.bottom, this.y + this.lineH);
-    const pos = { h: 1, w: GRID_COLUMNS, x: 0, y };
+  /** Marks the line of a row header with an explicit `y` as taken, before anything is placed. */
+  reserveRow(y: number | undefined): void {
+    if (y !== undefined) this.take(0, y, GRID_COLUMNS, 1);
+  }
+
+  /** A full-width row header on line `explicitY`, else on the first free line below everything placed so far. */
+  row(explicitY?: number): GridPos {
+    let y = explicitY ?? Math.max(this.bottom, this.y + this.lineH);
+    if (explicitY === undefined) while (!this.free(0, y, GRID_COLUMNS, 1)) y++;
+    this.take(0, y, GRID_COLUMNS, 1);
     this.x = 0;
     this.y = y + 1;
     this.lineH = 0;
     this.bottom = y + 1;
-    // Called after a collapsed row's panels: the next thing starts right under the header.
-    const mark = () => {
-      this.x = 0;
-      this.y = y + 1;
-      this.lineH = 0;
-      this.bottom = y + 1;
-    };
-    return { pos, mark };
+    return { h: 1, w: GRID_COLUMNS, x: 0, y };
+  }
+
+  /** The first column at or after `from` where a w×h panel fits on line `y`. A panel wider than the grid fits only at 0. */
+  private freeColumn(from: number, y: number, w: number, h: number): number | undefined {
+    for (let x = from; x === 0 || x + w <= GRID_COLUMNS; x++) if (this.free(x, y, w, h)) return x;
+    return undefined;
+  }
+
+  private free(x: number, y: number, w: number, h: number): boolean {
+    const mask = columns(x, w);
+    for (let line = Math.max(0, y); line < y + h; line++) if ((this.taken[line] ?? 0) & mask) return false;
+    return true;
+  }
+
+  private take(x: number, y: number, w: number, h: number): void {
+    const mask = columns(x, w);
+    for (let line = Math.max(0, y); line < y + h; line++) this.taken[line] = (this.taken[line] ?? 0) | mask;
   }
 }
 
@@ -334,7 +502,8 @@ function panelJson(panel: PanelEntity, gridPos: GridPos, id: number, inherited?:
   const def = panel.panelDefinition;
   const own = datasourceRef(p.datasource) ?? inherited;
   const queries = (p.targets ?? []).filter(isQueryEntity);
-  const targets = queries.map((q, i) => targetJson(q, i, own));
+  // A query under a Mixed panel names its own datasource; one that names none goes to the default, not to Mixed.
+  const targets = queries.map((q, i) => targetJson(q, i, sameRef(own, MIXED) ? undefined : own));
   const refs = targets.map((t) => t.datasource as DataSourceRef | undefined);
   let datasource = own;
   if (!datasource && refs.length > 0) {
@@ -374,19 +543,29 @@ function panelJson(panel: PanelEntity, gridPos: GridPos, id: number, inherited?:
 /** A dashboard's `panels` array: rows and panels, laid out, with ids. */
 export function panelsJson(items: Array<PanelEntity | RowEntity>): Array<PanelJson | RowPanelJson> {
   const layout = new Layout();
+  // Panels on the dashboard's grid with both x and y, and rows with a y, take their cells first; a collapsed row's panels are laid out on their own.
+  for (const item of items) {
+    if (isRowEntity(item)) layout.reserveRow(item.props.gridPos?.y);
+    const onGrid = isRowEntity(item) ? (item.props.collapsed ? [] : (item.props.panels ?? [])) : [item];
+    for (const p of onGrid.filter(isPanelEntity)) layout.reserve(p.props.gridPos, p.panelDefinition.defaultSize);
+  }
   const ids = new Ids(explicitIds(items));
   const out: Array<PanelJson | RowPanelJson> = [];
   for (const item of items) {
     if (isRowEntity(item)) {
       const r = item.props;
-      const { pos, mark } = layout.row();
+      const pos = layout.row(r.gridPos?.y);
       const rowId = ids.take(r.id);
       const rowRef = datasourceRef(r.datasource);
-      const children = (r.panels ?? []).filter(isPanelEntity).map((p) => {
-        const gp = layout.place(p.props.gridPos, p.panelDefinition.defaultSize);
+      const collapsed = r.collapsed ?? false;
+      // A collapsed row's panels sit under its header on a grid of their own; the next item starts right under the header.
+      const rowLayout = collapsed ? new Layout(pos.y + 1) : layout;
+      const panels = (r.panels ?? []).filter(isPanelEntity);
+      if (collapsed) for (const p of panels) rowLayout.reserve(p.props.gridPos, p.panelDefinition.defaultSize);
+      const children = panels.map((p) => {
+        const gp = rowLayout.place(p.props.gridPos, p.panelDefinition.defaultSize);
         return panelJson(p, gp, ids.take(p.props.id), rowRef);
       });
-      const collapsed = r.collapsed ?? false;
       out.push(
         compact({
           type: "row" as const,
@@ -399,8 +578,7 @@ export function panelsJson(items: Array<PanelEntity | RowEntity>): Array<PanelJs
           repeat: repeatName(r.repeat),
         }),
       );
-      if (collapsed) mark();
-      else out.push(...children);
+      if (!collapsed) out.push(...children);
     } else if (isPanelEntity(item)) {
       const gp = layout.place(item.props.gridPos, item.panelDefinition.defaultSize);
       out.push(panelJson(item, gp, ids.take(item.props.id)));
@@ -422,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,
@@ -431,7 +609,7 @@ export function renderDashboard(dashboard: DashboardEntity, exportName?: string)
     liveNow: p.liveNow,
     panels: panelsJson(p.panels ?? []),
     refresh: p.refresh,
-    schemaVersion: DASHBOARD_SCHEMA_VERSION,
+    schemaVersion: p.schemaVersion ?? DASHBOARD_SCHEMA_VERSION,
     tags: p.tags ?? [],
     templating: { list: (p.variables ?? []).filter(isVariableEntity).map(variableModel) },
     time: p.time ?? { from: "now-6h", to: "now" },
@@ -450,9 +628,9 @@ export function dashboardJson(dashboard: DashboardEntity, exportName?: string):
 
 // ── Datasources and providers ───────────────────────────────────
 
-/** Replace every declared `Datasource` inside plugin settings with its uid. */
+/** Replace every declared or external datasource inside plugin settings with its uid. */
 function resolveNested(value: unknown): unknown {
-  if (isDatasourceEntity(value)) return value.uid;
+  if (isDatasourceDeclaration(value)) return value.uid;
   if (Array.isArray(value)) return value.map(resolveNested);
   if (value && typeof value === "object" && Object.getPrototypeOf(value) === Object.prototype) {
     return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, resolveNested(v)]));
@@ -483,8 +661,13 @@ export function provisionedDatasource(ds: DatasourceEntity): ProvisionedDatasour
   });
 }
 
+/** One `ExternalDatasource` as the checks and the index see it. */
+export function externalDatasourceRecord(ds: ExternalDatasourceEntity): ExternalDatasourceRecord {
+  return compact({ type: ds.datasourceType, uid: ds.uid, name: ds.props.name });
+}
+
 /** 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,
@@ -506,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. */
@@ -516,8 +716,20 @@ export function dashboardProvidersYaml(providers: ProvisionedProvider[]): string
   return yamlFile("Grafana dashboard provisioning, generated by chant.", { apiVersion: 1, providers });
 }
 
+/**
+ * A dashboard's `folder` as its directory under `dashboards/`: one
+ * 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). Empty for the General
+ * folder.
+ */
 function folderDir(folder: string): string {
-  return folder.replace(/[/\\]+/g, "-").replace(/^\.+/, "").trim() || "General";
+  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 ─────────────────────────────────────────────
@@ -534,37 +746,64 @@ export function buildGrafana(entities: Map<string, Declarable> | Iterable<Declar
     .map(([, e]) => provisionedDatasource(e as DatasourceEntity))
     .sort((a, b) => a.name.localeCompare(b.name));
 
+  const externalDatasources: ExternalDatasourceRecord[] = named
+    .filter(([, e]) => isExternalDatasource(e))
+    .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;
     const json = renderDashboard(e, name);
     const uid = json.uid as string;
     const folder = e.props.folder;
-    const dir = folder ? `${DASHBOARDS_DIR}/${folderDir(folder)}` : DASHBOARDS_DIR;
+    const sub = folder ? folderDir(folder) : "";
+    const dir = sub ? `${DASHBOARDS_DIR}/${sub}` : DASHBOARDS_DIR;
     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)
       : dashboards.length > 0
-        ? [provisionedProvider({ name: "chant" })]
+        ? [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, providers, 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. */