@intentius/chant-lexicon-grafana 0.97.0 → 0.99.0

package/src/build.ts

@@ -10,7 +10,7 @@
 
 import { dump } from "js-yaml";
 import type { Declarable } from "@intentius/chant/declarable";
-import { isDatasourceEntity, type DatasourceEntity, type DatasourceRef } from "./datasource";
+import { isDatasourceDeclaration, isDatasourceEntity, isExternalDatasource, type DatasourceEntity, type DatasourceRef, type ExternalDatasourceEntity } from "./datasource";
 import {
   isDashboardEntity,
   isDashboardProviderEntity,
@@ -34,6 +34,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 };
 
@@ -90,7 +92,11 @@ 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[];
+  /** 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. */
@@ -101,9 +107,20 @@ export interface GrafanaIndex {
   grafanaSchema: string;
   dashboards: Array<{ uid: string; title: string; folder?: string; file: string }>;
   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 +133,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 +171,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[] }) {
@@ -192,13 +225,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": {
@@ -266,47 +302,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 +433,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 +474,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 +509,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)));
@@ -431,7 +540,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 +559,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,6 +592,11 @@ 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 {
   const pinnedFolder = p.folder !== undefined || p.folderUid !== undefined;
@@ -516,8 +630,21 @@ 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 `/`-separated level, 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.
+ */
 function folderDir(folder: string): string {
-  return folder.replace(/[/\\]+/g, "-").replace(/^\.+/, "").trim() || "General";
+  return folder
+    .split("/")
+    .map((level) => level.replace(/\\+/g, "-").trim().replace(/^\.+/, "").trim())
+    .filter((level) => level !== "")
+    .join("/");
 }
 
 // ── The whole build ─────────────────────────────────────────────
@@ -534,13 +661,19 @@ 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));
+
   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`;
@@ -552,19 +685,23 @@ export function buildGrafana(entities: Map<string, Declarable> | Iterable<Declar
     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 (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 })),
     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, ...(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,13 +5,23 @@
  */
 
 import type { LexiconEntry } from "@intentius/chant/lsp/lexicon-providers";
-import { DATASOURCE_TYPE } from "./datasource";
+import { DATASOURCE_TYPE, EXTERNAL_DATASOURCE_TYPE } from "./datasource";
 import { DASHBOARD_TYPE, DASHBOARD_PROVIDER_TYPE } from "./dashboard";
 import * as panels from "./panels";
 import * as queries from "./query";
 import { VARIABLE_TYPE_PREFIX } from "./variables";
+import {
+  ALERT_QUERY_TYPE,
+  ALERT_RULE_GROUP_TYPE,
+  ALERT_RULE_TYPE,
+  CONTACT_POINT_TYPE,
+  EXPRESSION_TYPE_PREFIX,
+  MUTE_TIMING_TYPE,
+  NOTIFICATION_POLICY_TYPE,
+  NOTIFICATION_TEMPLATE_TYPE,
+} from "./alerting";
 
-export type CatalogKind = "dashboard" | "datasource" | "provider" | "panel" | "row" | "query" | "variable";
+export type CatalogKind = "dashboard" | "datasource" | "provider" | "panel" | "row" | "query" | "variable" | "alerting" | "expression";
 
 export interface CatalogEntry {
   className: string;
@@ -59,6 +69,15 @@ const VARIABLES: Array<[string, string, string]> = [
   ["TextboxVariable", "textbox", "A free-text box"],
 ];
 
+const EXPRESSIONS: Array<[string, string, string]> = [
+  ["ReduceExpression", "reduce", "A server-side expression reducing each series to one number (last, mean, max, ...)"],
+  ["MathExpression", "math", "A server-side math expression over other results by refId, e.g. $A / $B"],
+  ["ThresholdExpression", "threshold", "A server-side threshold, with an optional recovery threshold"],
+  ["ResampleExpression", "resample", "A server-side expression resampling a time series to a fixed window"],
+  ["ClassicConditionsExpression", "classic_conditions", "Grafana's legacy classic conditions, as a server-side expression"],
+  ["SqlExpression", "sql", "A server-side SQL expression over the other results"],
+];
+
 export const BUILTIN_CATALOG: CatalogEntry[] = [
   {
     className: "Dashboard",
@@ -74,6 +93,13 @@ export const BUILTIN_CATALOG: CatalogEntry[] = [
     entityKind: "resource",
     description: "A datasource, declared once and referenced by panels, queries and variables",
   },
+  {
+    className: "ExternalDatasource",
+    entityType: EXTERNAL_DATASOURCE_TYPE,
+    kind: "datasource",
+    entityKind: "resource",
+    description: "A datasource that already exists in Grafana: referenced like a Datasource and checked by GRAF101/GRAF102, never provisioned",
+  },
   {
     className: "DashboardProvider",
     entityType: DASHBOARD_PROVIDER_TYPE,
@@ -88,6 +114,64 @@ export const BUILTIN_CATALOG: CatalogEntry[] = [
     entityKind: "property",
     description: "A full-width row header; its panels are placed below it, or inside it when collapsed",
   },
+  {
+    className: "AlertRuleGroup",
+    entityType: ALERT_RULE_GROUP_TYPE,
+    kind: "alerting",
+    entityKind: "resource",
+    description: "A group of Grafana-managed alert and recording rules in a folder, evaluated together at one interval",
+  },
+  {
+    className: "ContactPoint",
+    entityType: CONTACT_POINT_TYPE,
+    kind: "alerting",
+    entityKind: "resource",
+    description: "A contact point: the integrations (email, Slack, webhook, ...) alerts are sent to, under one name",
+  },
+  {
+    className: "NotificationPolicy",
+    entityType: NOTIFICATION_POLICY_TYPE,
+    kind: "alerting",
+    entityKind: "resource",
+    description: "An organisation's notification policy tree: the root receiver and the routes that match alerts to contact points",
+  },
+  {
+    className: "MuteTiming",
+    entityType: MUTE_TIMING_TYPE,
+    kind: "alerting",
+    entityKind: "resource",
+    description: "A named time interval that mutes (or, as active_time_intervals, enables) notifications",
+  },
+  {
+    className: "NotificationTemplate",
+    entityType: NOTIFICATION_TEMPLATE_TYPE,
+    kind: "alerting",
+    entityKind: "resource",
+    description: "A notification template group, Go templates contact point settings can use",
+  },
+  {
+    className: "AlertRule",
+    entityType: ALERT_RULE_TYPE,
+    kind: "alerting",
+    entityKind: "property",
+    description: "A Grafana-managed alert or recording rule: queries, expressions and the condition that fires it",
+  },
+  {
+    className: "AlertQuery",
+    entityType: ALERT_QUERY_TYPE,
+    kind: "alerting",
+    entityKind: "property",
+    description: "A datasource query of an alert rule, with its model as Grafana stores it and its time range",
+  },
+  ...EXPRESSIONS.map(
+    ([className, type, description]): CatalogEntry => ({
+      className,
+      entityType: `${EXPRESSION_TYPE_PREFIX}${type}`,
+      kind: "expression",
+      entityKind: "property",
+      description,
+    }),
+  ),
   ...panelEntries,
   ...queryEntries,
   ...VARIABLES.map(

package/src/codegen/docs.ts

@@ -13,7 +13,8 @@ function serviceFromType(resourceType: string): string {
 }
 
 const overview = `The grafana lexicon types what a [Grafana](https://grafana.com/docs/grafana/latest/) dashboard
-shows: datasources, dashboards, rows, panels, queries and variables. \`chant build\`
+shows: datasources, dashboards, rows, panels, queries and variables, and
+Grafana-managed alerting. \`chant build\`
 writes one JSON file per dashboard, the JSON Grafana imports as it is, plus the
 provisioning files Grafana reads for dashboards and datasources. Grafana server
 settings, users and plugins are out of scope.
@@ -28,11 +29,29 @@ const requests = new TimeSeriesPanel({ title: "Requests per second", datasource:
 export const overview = new Dashboard({ title: "Overview", panels: [requests] });
 \`\`\`
 
-Panels: time series, stat, gauge, table, logs, traces, heatmap and text, plus
-rows. Queries: Prometheus (PromQL), Tempo (TraceQL) and Loki (LogQL). Panel
+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, and every build validates the dashboards against the same schemas.
+version, corrected against Grafana's CUE, and track Grafana 12.4 and 13.x. Every
+build validates the dashboards against the same schemas.
 \`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
+[Importing Dashboards](./importing/)). \`chant lifecycle diff --live\` reports
+a dashboard edited in Grafana as drift, property by property, and
+\`chant import --from <env>\` writes a running Grafana's dashboards as
+TypeScript (see [Drift and Live Export](./observing/)). \`grafanaApply\` writes
+a build to a running Grafana over its HTTP API, with folders and library
+panels, and prunes the project's own dashboards and folders (see
+[Apply over the API](./applying/)).
+
+Grafana-managed alerting is typed too: rule groups with their queries and
+server-side expressions (reduce, math, threshold, resample, classic
+conditions, SQL), contact points, the notification policy tree, mute timings
+and templates, written to Grafana's alerting provisioning file.
+\`SloAlertRules\` turns a prometheus \`Slo\` into burn-rate alert rules. See
+[Alerting](./alerting/).
 
 Three composites build whole dashboards from declarations in other lexicons:
 \`RedDashboard\` from an otel \`spanmetrics\` connector, \`SloDashboard\` from a
@@ -40,10 +59,17 @@ prometheus \`Slo\` and \`AgentDashboard\` from the otel GenAI preset. Metric nam
 come from the declaration, so renaming one moves the panels. See
 [Dashboards from Declarations](./composites/).
 
-Checks catch a query aimed at a datasource nobody declared (GRAF101) or of the
+Checks catch a query aimed at a datasource nobody declared, with
+\`Datasource\` or \`ExternalDatasource\` (GRAF101), or of the
 wrong type (GRAF102), a \`$variable\` the dashboard doesn't declare (GRAF103),
 duplicate uids and ids (GRAF104), panels off the grid or overlapping (GRAF105),
-and anything Grafana's dashboard schema rejects (GRAF107).
+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
+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).
 `;
 
 const outputFormat = `The grafana lexicon writes Grafana's own files, keyed by path under the
@@ -54,9 +80,12 @@ directory of the \`-o\` output:
 - \`provisioning/datasources/chant.yaml\`: every declared datasource.
 - \`provisioning/dashboards/chant.yaml\`: a file provider for the dashboards
   directory; a default one unless a \`DashboardProvider\` is declared.
+- \`provisioning/alerting/chant.yaml\`: rule groups, contact points, the
+  notification policy tree, mute timings and templates, when the build
+  declares any.
 
 The primary output (the \`-o\` file itself) is a JSON index of the dashboards,
-datasources and files that were built.
+datasources, alerting and files that were built.
 
 - Dashboard JSON carries the pinned schema's \`schemaVersion\`, no numeric \`id\`,
   and every field Grafana's schema requires (link defaults, an empty
@@ -67,8 +96,12 @@ datasources and files that were built.
   referenced, and as its uid inside another datasource's \`jsonData\`.
 - \`chant build\` rewrites JSON files with sorted keys; Grafana does not care
   about key order.
-- Grafana's files have no metadata channel chant could use without changing
-  what Grafana imports, so no ownership marker is stamped.
+- The dashboard JSON carries no ownership marker. Grafana keeps who manages a
+  dashboard in the resource's metadata on its \`dashboard.grafana.app\` API,
+  not in the JSON: for a provisioned dashboard, the name of the provider that
+  loaded it, which is \`chant\` unless a \`DashboardProvider\` names another.
+  \`chant lifecycle diff --live\` reads that back (see
+  [Drift and Live Export](../observing/)).
 `;
 
 export async function generateDocs(opts?: { verbose?: boolean }): Promise<void> {

package/src/codegen/schema-types.ts

@@ -1,9 +1,9 @@
 /**
  * JSON Schema (draft-07, the subset cog emits) to TypeScript declarations.
  *
- * Each vendored schema becomes one module under `src/schema/`: one exported
- * type per entry in `definitions`, with the schema's descriptions as doc
- * comments. `required` is kept, so the types say what the schema says; the
+ * Each vendored schema, with its correction overlay applied, becomes one
+ * module under `src/schema/`: one exported type per entry in `definitions`,
+ * with the schema's descriptions as doc comments. `required` is kept, so the types say what the schema says; the
  * entity props wrap panel options in `DeepPartial` where Grafana fills the
  * rest in on import.
  */
@@ -99,6 +99,15 @@ function objectType(node: Node, indent: string): string {
   return lines.length === 2 ? "Record<string, never>" : lines.join("\n");
 }
 
+/**
+ * A branch that only constrains which keys are present (`{ required: [...] }`),
+ * like the overlay's "a panel has a `type` or a `libraryPanel`". It says
+ * nothing about the shape, so the type ignores it and validation enforces it.
+ */
+function constraintOnly(branches: Node[] | undefined): boolean {
+  return Array.isArray(branches) && branches.every((b) => Object.keys(b).every((k) => k === "required"));
+}
+
 /** The TypeScript type for one schema node. */
 export function tsType(node: Node | boolean | undefined, indent = ""): string {
   if (node === undefined || node === true) return "unknown";
@@ -106,8 +115,8 @@ export function tsType(node: Node | boolean | undefined, indent = ""): string {
   if (node.$ref) return refName(node.$ref);
   if (node.const !== undefined) return literal(node.const);
   if (Array.isArray(node.enum)) return union(node.enum.map(literal));
-  if (node.oneOf) return union(node.oneOf.map((n) => paren(tsType(n, indent))));
-  if (node.anyOf) return union(node.anyOf.map((n) => paren(tsType(n, indent))));
+  if (node.oneOf && !constraintOnly(node.oneOf)) return union(node.oneOf.map((n) => paren(tsType(n, indent))));
+  if (node.anyOf && !constraintOnly(node.anyOf)) return union(node.anyOf.map((n) => paren(tsType(n, indent))));
   if (node.allOf) return node.allOf.map((n) => paren(tsType(n, indent))).join(" & ");
 
   const types = Array.isArray(node.type) ? node.type : node.type ? [node.type] : [];
@@ -154,7 +163,8 @@ export function schemaModule(name: SchemaName, schema: Record<string, unknown>,
   const defs = (schema.definitions ?? {}) as Record<string, Node>;
   const out: string[] = [
     "// Code generated by chant generate from the vendored Grafana schema",
-    `// src/spec/schemas/${name}.jsonschema.json (see src/pin.ts). DO NOT EDIT.`,
+    `// src/spec/schemas/${name}.jsonschema.json (see src/pin.ts) and its correction`,
+    "// overlay in src/spec/overlay/ (see src/spec/overlay.ts). DO NOT EDIT.",
     "/* eslint-disable */",
     "",
   ];