@intentius/chant-lexicon-grafana 0.124.30 → 0.124.32

package/dist/build.js

@@ -0,0 +1,767 @@
+/**
+ * From declared entities to Grafana's own files: dashboard JSON, the
+ * datasource provisioning file and the dashboard provisioning file.
+ *
+ * Plain functions, so another lexicon (a k8s ConfigMap, a docker volume)
+ * can render the same files with `grafanaFiles()` or one dashboard with
+ * `dashboardJson()`, and the serializer is a thin wrapper around
+ * `buildGrafana()`.
+ */
+import { dump } from "js-yaml";
+import { isDatasourceDeclaration, isDatasourceEntity, isDatasourceProvisioningEntity, isExternalDatasource, } from "./datasource.js";
+import { isDashboardEntity, isDashboardProviderEntity, DEFAULT_DASHBOARDS_PATH, } from "./dashboard.js";
+import { annotationJson } from "./annotations.js";
+import { folderLevels, folderUidFor, isFolderEntity } from "./folder.js";
+import { resolveFolders } from "./api/folders.js";
+import { isPanelEntity, isRowEntity } from "./panels.js";
+import { isLibraryPanelEntity, isLibraryPanelRefEntity, referencedLibraryPanel, } from "./library-panel.js";
+import { LIBRARY_PANEL_KIND } from "./api/library-panels.js";
+import { isQueryEntity } from "./query.js";
+import { isDatasourceVariable, isVariableEntity } from "./variables.js";
+import { DASHBOARD_SCHEMA_VERSION } from "./schema/dashboard.gen.js";
+import { GRAFANA_SCHEMA_PIN } from "./pin.js";
+import { compact, slugUid } from "./util.js";
+import { ALERTING_FILE, alertingYaml, buildAlerting } from "./alerting-build.js";
+import { DEFAULT_PROVIDER_NAME } from "./ownership.js";
+/** Grafana's grid is 24 columns wide. */
+export const GRID_COLUMNS = 24;
+/** Where each file goes, relative to the build output directory. */
+export const DATASOURCES_FILE = "provisioning/datasources/chant.yaml";
+export const DASHBOARD_PROVIDERS_FILE = "provisioning/dashboards/chant.yaml";
+export const DASHBOARDS_DIR = "dashboards";
+// ── References ──────────────────────────────────────────────────
+function isRef(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.type === "string" &&
+        typeof value.uid === "string" &&
+        !("lexicon" in value));
+}
+/** The `{ type, uid }` Grafana stores for a datasource (declared or external), a datasource variable, or a ref. */
+export function datasourceRef(input) {
+    if (input === undefined || input === null)
+        return undefined;
+    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, an ExternalDatasource, a DatasourceVariable or a { type, uid } ref");
+}
+function sameRef(a, b) {
+    return a?.type === b?.type && a?.uid === b?.uid;
+}
+const MIXED = { type: "datasource", uid: "-- Mixed --" };
+// ── Links ───────────────────────────────────────────────────────
+function dashboardLink(link) {
+    return compact({
+        title: link.title,
+        type: link.type ?? "link",
+        url: link.url,
+        icon: link.icon ?? "external link",
+        tooltip: link.tooltip ?? "",
+        tags: link.tags ?? [],
+        asDropdown: link.asDropdown ?? false,
+        placement: link.placement,
+        targetBlank: link.targetBlank ?? false,
+        includeVars: link.includeVars ?? false,
+        keepTime: link.keepTime ?? false,
+    });
+}
+// ── Variables ───────────────────────────────────────────────────
+const HIDE = { label: 0, valueOnly: 1, hidden: 2, controlsMenu: 3 };
+const REFRESH = { never: 0, onLoad: 1, onTimeRangeChange: 2 };
+/** A custom variable value in its `query`: a comma is escaped as `\\,`, and one already escaped is left alone. */
+function escapeCustom(v) {
+    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) {
+    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, current) {
+    const selected = current ? (Array.isArray(current.value) ? current.value : [current.value]) : values.slice(0, 1);
+    return values.map((v) => ({ selected: selected.includes(v), text: v, value: v }));
+}
+/** One variable as Grafana's `templating.list` entry. */
+export function variableModel(variable) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const p = variable.props;
+    const common = {
+        type: variable.variableKind,
+        name: p.name,
+        label: p.label,
+        description: p.description,
+        hide: p.hide === undefined ? undefined : HIDE[p.hide],
+        skipUrlSync: p.skipUrlSync,
+    };
+    const multi = { multi: p.multi, includeAll: p.includeAll, allValue: p.allValue, allowCustomValue: p.allowCustomValue };
+    switch (variable.variableKind) {
+        case "query":
+            return compact({
+                ...common,
+                datasource: datasourceRef(p.datasource),
+                query: p.query,
+                definition: p.definition ?? queryText(p.query),
+                regex: p.regex,
+                refresh: REFRESH[(p.refresh ?? "onLoad")],
+                sort: p.sort,
+                ...multi,
+                current: p.current,
+                options: [],
+            });
+        case "custom": {
+            const values = p.values;
+            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,
+                ...multi,
+                current,
+                options: options.map((o) => ({ selected: selected.includes(o.value), ...o })),
+            });
+        }
+        case "interval": {
+            const values = p.values;
+            const current = p.current ?? (values[0] !== undefined ? { text: values[0], value: values[0] } : undefined);
+            return compact({
+                ...common,
+                query: values.join(","),
+                current,
+                options: optionsOf(values, current),
+                auto: p.auto ?? false,
+                auto_count: p.autoCount ?? 30,
+                auto_min: p.autoMin ?? "10s",
+                refresh: 2,
+            });
+        }
+        case "datasource":
+            return compact({
+                ...common,
+                query: p.pluginType,
+                regex: p.regex ?? "",
+                ...multi,
+                current: p.current,
+                refresh: 1,
+                options: [],
+            });
+        case "constant":
+            return compact({
+                ...common,
+                hide: 2,
+                query: p.value,
+                current: { text: p.value, value: p.value },
+            });
+        case "textbox":
+            return compact({
+                ...common,
+                query: p.value ?? "",
+                current: { text: p.value ?? "", value: p.value ?? "" },
+            });
+        case "adhoc":
+            return compact({
+                ...common,
+                datasource: datasourceRef(p.datasource),
+                filters: p.filters ?? [],
+                baseFilters: p.baseFilters ?? [],
+                defaultKeys: p.defaultKeys,
+                allowCustomValue: p.allowCustomValue,
+                enableGroupBy: p.enableGroupBy,
+            });
+        case "groupby": {
+            const options = p.options?.map((o) => (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,
+            });
+        }
+        case "switch": {
+            const on = p.enabledValue ?? "true";
+            const off = 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 },
+                ],
+            });
+        }
+    }
+}
+/** The text of a variable query: the string, or an object query's `query`. */
+function queryText(query) {
+    if (typeof query === "string")
+        return query;
+    if (query && typeof query === "object" && typeof query.query === "string")
+        return query.query;
+    return undefined;
+}
+// ── Panels and layout ───────────────────────────────────────────
+function repeatName(repeat) {
+    if (repeat === undefined)
+        return undefined;
+    return typeof repeat === "string" ? repeat : repeat.variableName;
+}
+const REF_IDS = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
+function refIdAt(i) {
+    return i < REF_IDS.length ? REF_IDS[i] : `${REF_IDS[Math.floor(i / REF_IDS.length) - 1]}${REF_IDS[i % REF_IDS.length]}`;
+}
+/** One query as a panel target. */
+export function targetJson(query, index, panelDatasource) {
+    const def = query.queryDefinition;
+    const { datasource, ...model } = query.props;
+    const ref = datasourceRef(datasource) ?? panelDatasource;
+    return compact({
+        datasource: ref,
+        refId: model.refId ?? refIdAt(index),
+        ...(def.defaults ?? {}),
+        ...model,
+    });
+}
+/** A bitmask of grid columns [x, x + w), clipped to the grid. */
+function columns(x, w) {
+    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 {
+    constructor(top = 0) {
+        this.x = 0;
+        this.lineH = 0;
+        /** Taken cells: one column bitmask per grid line. */
+        this.taken = [];
+        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, size) {
+        if (gp?.x === undefined || gp?.y === undefined)
+            return;
+        this.take(gp.x, gp.y, gp.w ?? size.w, gp.h ?? size.h);
+    }
+    place(gp, size) {
+        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 (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;
+        }
+    }
+    /** Marks the line of a row header with an explicit `y` as taken, before anything is placed. */
+    reserveRow(y) {
+        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) {
+        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;
+        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. */
+    freeColumn(from, y, w, h) {
+        for (let x = from; x === 0 || x + w <= GRID_COLUMNS; x++)
+            if (this.free(x, y, w, h))
+                return x;
+        return undefined;
+    }
+    free(x, y, w, h) {
+        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;
+    }
+    take(x, y, w, h) {
+        const mask = columns(x, w);
+        for (let line = Math.max(0, y); line < y + h; line++)
+            this.taken[line] = (this.taken[line] ?? 0) | mask;
+    }
+}
+class Ids {
+    constructor(taken) {
+        this.taken = taken;
+        this.next = 1;
+    }
+    take(explicit) {
+        if (explicit !== undefined)
+            return explicit;
+        while (this.taken.has(this.next))
+            this.next++;
+        return this.next++;
+    }
+}
+/** The `id` an item sets, if any. A `LibraryPanel` listed as it is has none: its panel's `id` is not the reference's. */
+function ownId(item) {
+    if (isLibraryPanelEntity(item))
+        return undefined;
+    return typeof item.props.id === "number" ? item.props.id : undefined;
+}
+/** The `gridPos` an item sets, if any. */
+function ownGridPos(item) {
+    return isLibraryPanelEntity(item) ? undefined : item.props.gridPos;
+}
+/** The size an item takes when its `gridPos` leaves `w` or `h` out: its panel class's, for a library panel the panel it holds. */
+function defaultSize(item) {
+    if (isPanelEntity(item))
+        return item.panelDefinition.defaultSize;
+    const lp = referencedLibraryPanel(item).entity;
+    return lp && isPanelEntity(lp.props.panel) ? lp.props.panel.panelDefinition.defaultSize : LIBRARY_PANEL_SIZE;
+}
+/** The size of a reference to a library panel the project does not declare, when its `gridPos` leaves it out. */
+const LIBRARY_PANEL_SIZE = { w: 12, h: 8 };
+function isPlaceable(item) {
+    return isPanelEntity(item) || isLibraryPanelEntity(item) || isLibraryPanelRefEntity(item);
+}
+function explicitIds(items) {
+    const out = new Set();
+    for (const item of items) {
+        const id = ownId(item);
+        if (id !== undefined)
+            out.add(id);
+        if (isRowEntity(item))
+            for (const p of item.props.panels ?? [])
+                if (ownId(p) !== undefined)
+                    out.add(ownId(p));
+    }
+    return out;
+}
+/** A library panel reference as the dashboard holds it: Grafana draws the panel from the library. */
+function libraryRefJson(item, gridPos, id) {
+    const { uid, name } = referencedLibraryPanel(item);
+    return compact({
+        id,
+        gridPos,
+        libraryPanel: { uid, name },
+        title: isLibraryPanelRefEntity(item) ? item.props.title : undefined,
+    });
+}
+/** One placed item: a panel, or a reference to a library panel. */
+function itemJson(item, gridPos, id) {
+    return isPanelEntity(item) ? panelJson(item, gridPos, id) : libraryRefJson(item, gridPos, id);
+}
+function panelJson(panel, gridPos, id) {
+    const p = panel.props;
+    const def = panel.panelDefinition;
+    const own = datasourceRef(p.datasource);
+    const queries = (p.targets ?? []).filter(isQueryEntity);
+    // 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);
+    let datasource = own;
+    if (!datasource && refs.length > 0) {
+        datasource = refs.every((r) => sameRef(r, refs[0])) ? refs[0] : MIXED;
+    }
+    else if (datasource && refs.some((r) => r && !sameRef(r, datasource))) {
+        datasource = MIXED;
+    }
+    const fieldConfig = {
+        defaults: { ...(p.fieldConfig?.defaults ?? {}) },
+        overrides: p.fieldConfig?.overrides ?? [],
+    };
+    return compact({
+        type: def.type,
+        id,
+        title: p.title ?? "",
+        description: p.description,
+        gridPos,
+        datasource,
+        targets: targets.length > 0 ? targets : undefined,
+        options: (p.options ?? {}),
+        fieldConfig,
+        transformations: p.transformations,
+        links: p.links?.map(dashboardLink),
+        repeat: repeatName(p.repeat),
+        repeatDirection: p.repeatDirection,
+        maxPerRow: p.maxPerRow,
+        maxDataPoints: p.maxDataPoints,
+        interval: p.interval,
+        timeFrom: p.timeFrom,
+        timeShift: p.timeShift,
+        hideTimeOverride: p.hideTimeOverride,
+        transparent: p.transparent,
+        pluginVersion: p.pluginVersion,
+    });
+}
+/** A dashboard's `panels` array: rows, panels and library panel references, laid out, with ids. */
+export function panelsJson(items) {
+    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(isPlaceable))
+            layout.reserve(ownGridPos(p), defaultSize(p));
+    }
+    const ids = new Ids(explicitIds(items));
+    const out = [];
+    for (const item of items) {
+        if (isRowEntity(item)) {
+            const r = item.props;
+            const pos = layout.row(r.gridPos?.y);
+            const rowId = ids.take(r.id);
+            const rowRef = datasourceRef(r.datasource);
+            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(isPlaceable);
+            if (collapsed)
+                for (const p of panels)
+                    rowLayout.reserve(ownGridPos(p), defaultSize(p));
+            const children = panels.map((p) => {
+                const gp = rowLayout.place(ownGridPos(p), defaultSize(p));
+                return itemJson(p, gp, ids.take(ownId(p)));
+            });
+            out.push(compact({
+                type: "row",
+                collapsed,
+                title: r.title,
+                datasource: rowRef,
+                gridPos: pos,
+                id: rowId,
+                panels: collapsed ? children : [],
+                repeat: repeatName(r.repeat),
+            }));
+            if (!collapsed)
+                out.push(...children);
+        }
+        else if (isPlaceable(item)) {
+            const gp = layout.place(ownGridPos(item), defaultSize(item));
+            out.push(itemJson(item, gp, ids.take(ownId(item))));
+        }
+    }
+    return out;
+}
+// ── Dashboards ──────────────────────────────────────────────────
+const GRAPH_TOOLTIP = { default: 0, sharedCrosshair: 1, sharedTooltip: 2 };
+/** The dashboard's uid: its own, else from its export name, else from its title. */
+export function dashboardUid(dashboard, exportName) {
+    return dashboard.props.uid ?? slugUid(exportName ?? dashboard.props.title);
+}
+/** Every `LibraryPanel` a dashboard places, top level and in rows, each once, in order. */
+export function dashboardLibraryPanels(dashboard) {
+    const out = new Map();
+    const visit = (item) => {
+        if (!isLibraryPanelEntity(item) && !isLibraryPanelRefEntity(item))
+            return;
+        const lp = referencedLibraryPanel(item).entity;
+        if (!lp)
+            return;
+        const prior = out.get(lp.uid);
+        if (prior && prior !== lp)
+            throw new Error(`grafana: dashboard "${dashboard.props.title}" places two different LibraryPanels with the uid "${lp.uid}"`);
+        out.set(lp.uid, lp);
+    };
+    for (const item of dashboard.props.panels ?? []) {
+        if (isRowEntity(item))
+            for (const p of item.props.panels ?? [])
+                visit(p);
+        else
+            visit(item);
+    }
+    return [...out.values()];
+}
+/** A library panel's own panel JSON: a panel's, without the `gridPos` and `id` each reference has. */
+export function libraryPanelModel(lp) {
+    if (!isPanelEntity(lp.props.panel))
+        throw new Error(`grafana: LibraryPanel "${lp.props.name}" has no panel`);
+    const { gridPos: _gridPos, id: _id, ...model } = panelJson(lp.props.panel, { h: 0, w: 0, x: 0, y: 0 }, 0);
+    return model;
+}
+/**
+ * The `__elements` entry of a library panel, as Grafana's "Export for
+ * sharing externally" writes it, plus the uid of its folder when it names
+ * one (`folderUid` maps a folder path to its uid; the build passes the one
+ * that knows the declared `Folder`s).
+ */
+export function libraryElementJson(lp, folderUid = folderUidFor) {
+    const inFolder = lp.folderEntity?.uid ?? (lp.props.folder && folderLevels(lp.props.folder).length > 0 ? folderUid(lp.props.folder) : undefined);
+    return compact({ name: lp.props.name, uid: lp.uid, kind: LIBRARY_PANEL_KIND, model: libraryPanelModel(lp), folderUid: inFolder });
+}
+/**
+ * One dashboard as the JSON Grafana imports. The library panels it places
+ * are written into `__elements`, keyed by uid.
+ */
+export function renderDashboard(dashboard, exportName, folderUid) {
+    const p = dashboard.props;
+    const libraryPanels = dashboardLibraryPanels(dashboard);
+    return compact({
+        __elements: libraryPanels.length > 0 ? Object.fromEntries(libraryPanels.map((lp) => [lp.uid, libraryElementJson(lp, folderUid)])) : undefined,
+        annotations: { list: (p.annotations ?? []).map((a) => annotationJson(a, datasourceRef)) },
+        description: p.description,
+        editable: p.editable ?? true,
+        fiscalYearStartMonth: p.fiscalYearStartMonth ?? 0,
+        graphTooltip: GRAPH_TOOLTIP[p.graphTooltip ?? "default"],
+        links: (p.links ?? []).map(dashboardLink),
+        liveNow: p.liveNow,
+        panels: panelsJson(p.panels ?? []),
+        refresh: p.refresh,
+        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" },
+        timepicker: p.timepicker ?? {},
+        timezone: p.timezone ?? "browser",
+        title: p.title,
+        uid: dashboardUid(dashboard, exportName),
+        weekStart: p.weekStart ?? "",
+    });
+}
+/** One dashboard as formatted JSON text. */
+export function dashboardJson(dashboard, exportName) {
+    return `${JSON.stringify(renderDashboard(dashboard, exportName), null, 2)}\n`;
+}
+// ── Datasources and providers ───────────────────────────────────
+/** Replace every declared or external datasource inside plugin settings with its uid. */
+function resolveNested(value) {
+    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)]));
+    }
+    return value;
+}
+/** One datasource as a provisioning entry. */
+export function provisionedDatasource(ds) {
+    const p = ds.props;
+    return compact({
+        name: p.name,
+        type: p.type,
+        uid: ds.uid,
+        access: p.access ?? "proxy",
+        url: p.url,
+        isDefault: p.isDefault,
+        basicAuth: p.basicAuth,
+        basicAuthUser: p.basicAuthUser,
+        user: p.user,
+        database: p.database,
+        withCredentials: p.withCredentials,
+        jsonData: p.jsonData === undefined ? undefined : resolveNested(p.jsonData),
+        secureJsonData: p.secureJsonData,
+        editable: p.editable ?? false,
+        orgId: p.orgId,
+        version: p.version,
+    });
+}
+/** One `ExternalDatasource` as the checks and the index see it. */
+export function externalDatasourceRecord(ds) {
+    return compact({ type: ds.datasourceType, uid: ds.uid, name: ds.props.name });
+}
+/** One dashboard provider as a provisioning entry. */
+export function provisionedProvider(p) {
+    const pinnedFolder = p.folder !== undefined || p.folderUid !== undefined;
+    return compact({
+        name: p.name,
+        orgId: p.orgId ?? 1,
+        folder: p.folder ?? "",
+        folderUid: p.folderUid,
+        type: "file",
+        disableDeletion: p.disableDeletion ?? false,
+        allowUiUpdates: p.allowUiUpdates ?? false,
+        updateIntervalSeconds: p.updateIntervalSeconds ?? 30,
+        options: {
+            path: p.path ?? DEFAULT_DASHBOARDS_PATH,
+            foldersFromFilesStructure: p.foldersFromFilesStructure ?? !pinnedFolder,
+        },
+    });
+}
+function yamlFile(header, body) {
+    return `# ${header}\n${dump(body, { lineWidth: -1, noRefs: true, quotingType: '"' })}`;
+}
+/** `prune` and `deleteDatasources` as a build writes them: pruning on unless a `DatasourceProvisioning` turns it off. */
+export function datasourceFileSettings(props) {
+    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, settings = datasourceFileSettings(undefined)) {
+    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. */
+export function dashboardProvidersYaml(providers) {
+    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) {
+    return folderLevels(folder).join("/");
+}
+/** A `Folder` and every folder above it. */
+function withAncestors(folder, into) {
+    for (let f = folder; f; f = f.props.parent)
+        into.add(f);
+}
+// ── The whole build ─────────────────────────────────────────────
+/** Everything the grafana entities in a build render to. */
+export function buildGrafana(entities) {
+    const named = entities instanceof Map ? [...entities.entries()] : [...entities].map((e) => [undefined, e]);
+    const files = {};
+    // Sorted by name, so the provisioning file doesn't depend on which source file was read first.
+    const datasources = named
+        .filter(([, e]) => isDatasourceEntity(e))
+        .map(([, e]) => provisionedDatasource(e))
+        .sort((a, b) => a.name.localeCompare(b.name));
+    const externalDatasources = named
+        .filter(([, e]) => isExternalDatasource(e))
+        .map(([, e]) => externalDatasourceRecord(e))
+        .sort((a, b) => a.uid.localeCompare(b.uid));
+    // Library panels: every one declared, and every one a dashboard places.
+    const libraryPanels = new Set();
+    for (const [, e] of named) {
+        if (isLibraryPanelEntity(e))
+            libraryPanels.add(e);
+        else if (isDashboardEntity(e))
+            for (const lp of dashboardLibraryPanels(e))
+                libraryPanels.add(lp);
+    }
+    // Folders: every declared `Folder` and every one a dashboard or library panel holds, with their parents, pin uids; every path either names is a folder per level.
+    const declaredFolders = new Set();
+    for (const [, e] of named) {
+        if (isFolderEntity(e))
+            withAncestors(e, declaredFolders);
+        else if (isDashboardEntity(e) && e.folderEntity)
+            withAncestors(e.folderEntity, declaredFolders);
+    }
+    for (const lp of libraryPanels)
+        if (lp.folderEntity)
+            withAncestors(lp.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] : [])),
+            ...[...libraryPanels].flatMap((lp) => (lp.props.folder ? [lp.props.folder] : [])),
+        ],
+    }, { duplicateUids: "keep" });
+    const folderUidOfPath = (path) => resolved.uidOf(folderDir(path)) ?? folderUidFor(path);
+    const dashboards = [];
+    for (const [name, e] of named) {
+        if (!isDashboardEntity(e))
+            continue;
+        const json = renderDashboard(e, name, folderUidOfPath);
+        const uid = json.uid;
+        const folder = e.props.folder;
+        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`;
+        const folderUid = sub ? resolved.uidOf(sub) : undefined;
+        dashboards.push({ uid, title: e.props.title, ...(folder ? { folder } : {}), ...(folderUid ? { folderUid } : {}), file, json });
+    }
+    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.props);
+    const providers = declaredProviders.length > 0
+        ? declaredProviders.map(provisionedProvider)
+        : dashboards.length > 0
+            ? [provisionedProvider({ name: DEFAULT_PROVIDER_NAME })]
+            : [];
+    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 = {
+        grafanaSchema: `${GRAFANA_SCHEMA_PIN.source}@${GRAFANA_SCHEMA_PIN.ref}`,
+        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, folders: resolved.folders, datasourceFile, ...(alerting ? { alerting: alerting.file } : {}), files, index };
+}
+/** Every file the grafana entities render to, by path relative to the output directory. */
+export function grafanaFiles(entities) {
+    return buildGrafana(entities).files;
+}