@intentius/chant-lexicon-grafana 0.99.0 → 0.100.0

package/src/spec/schemas.ts

@@ -2,6 +2,12 @@
  * Read the vendored Grafana schemas (`src/spec/schemas/*.jsonschema.json`), check
  * them against the digests in `GRAFANA_SCHEMA_PIN`, and apply the correction
  * overlay (`src/spec/overlay/`, see `./overlay.ts`) on top.
+ *
+ * This is the source side, for `npm run generate`, the lexicon's own
+ * validate step, the importer's tests and the fetch scripts: it reads files
+ * next to this module. Nothing a build or lint runs imports it. Validation
+ * reads the generated `./schemas.gen.ts`, which generate writes from
+ * {@link loadSchema}.
  */
 
 import { createHash } from "crypto";
@@ -11,12 +17,7 @@ import { fileURLToPath } from "url";
 import { GRAFANA_SCHEMA_PIN, VENDORED_SCHEMA_NAMES, type SchemaName, type VendoredSchemaName } from "../pin";
 import { applyOverlay, loadOverlay } from "./overlay";
 
-/**
- * Where the vendored files live: beside this module, under `src/`, so they
- * ship with the source the package runs from and GRAF107 can read them.
- * A function, not a module-scope constant, so edge bundles that import the
- * lexicon never evaluate a filesystem path at load.
- */
+/** Where the vendored files live: beside this module, under `src/`. */
 export function schemasDir(): string {
   return join(dirname(fileURLToPath(import.meta.url)), "schemas");
 }
@@ -43,7 +44,8 @@ const parsed = new Map<SchemaName, Record<string, unknown>>();
 
 /**
  * One schema as the lexicon uses it: the vendored file with its overlay
- * applied (cached per process). Types, GRAF107 and validation all read this.
+ * applied (cached per process). Generate writes the types and
+ * `./schemas.gen.ts` from this, so GRAF107 sees the same schema.
  */
 export function loadSchema(name: SchemaName): Record<string, unknown> {
   let schema = parsed.get(name);

package/src/validate-alerting.ts

@@ -26,7 +26,7 @@ import { parseMatchers } from "@intentius/chant-lexicon-prometheus/matchers";
 import { EXPRESSION_DATASOURCE_UID } from "./alerting";
 import type { KnownDatasource } from "./datasource-refs";
 import { isValidUid } from "./util";
-import { validateExpressionSchema } from "./schema-validate";
+import { schemaValidationUnavailable, validateExpressionSchema } from "./schema-validate";
 import { checkGrafanaPromql } from "./promql-check";
 
 type Json = Record<string, unknown>;
@@ -152,7 +152,9 @@ export function checkRuleQueries(docs: readonly AlertingDoc[]): AlertingIssue[]
       if (q.datasourceUid !== EXPRESSION_DATASOURCE_UID) continue;
       const model = modelOf(q);
       const at = `expression ${String(q.refId ?? "?")}`;
-      for (const p of validateExpressionSchema(model)) {
+      const unavailable = schemaValidationUnavailable();
+      if (unavailable) push(`${at} was not checked against the Grafana expression schema: ${unavailable}.`, "warning");
+      for (const p of unavailable ? [] : validateExpressionSchema(model)) {
         if (p.severity === "error") push(`${at} ${p.path === "/" ? "" : `${p.path.slice(1)} `}${p.message} (Grafana expression schema).`);
       }
       for (const input of expressionInputs(model)) {

package/src/validate-output.ts

@@ -1,5 +1,5 @@
 /**
- * The checks behind GRAF101-GRAF109, GRAF111-GRAF114 and GRAF115, as plain
+ * The checks behind GRAF101-GRAF110, GRAF111-GRAF114 and GRAF115, as plain
  * functions over built Grafana output: dashboard JSON documents, provisioned
  * datasources, dashboard providers and alerting provisioning files (the
  * alerting checks are in `validate-alerting.ts`). The
@@ -17,6 +17,7 @@
 import type { ExternalDatasourceRecord, ProvisionedDatasource } from "./build";
 import { DASHBOARDS_DIR, GRID_COLUMNS } from "./build";
 import {
+  annotationsOf,
   datasourceUses,
   describePanel,
   knownDatasources,
@@ -26,9 +27,9 @@ import {
   type DatasourceRefJson,
   type KnownDatasource,
 } from "./datasource-refs";
-import { isBuiltinVariable } from "./variables";
+import { isBuiltinVariable, MULTI_VALUE_KINDS } from "./variables";
 import { isValidUid } from "./util";
-import { validateDashboardSchema } from "./schema-validate";
+import { schemaValidationUnavailable, validateDashboardSchema } from "./schema-validate";
 import { checkGrafanaPromql, prometheusQueries } from "./promql-check";
 import { checkAlertingIdentity, checkNotificationRefs, checkRuleDatasources, checkRulePromql, checkRuleQueries, type AlertingDoc } from "./validate-alerting";
 import { closestGrafanaUnit, isGrafanaUnit } from "./spec/units";
@@ -43,6 +44,7 @@ export type GrafanaIssueCode =
   | "GRAF107"
   | "GRAF108"
   | "GRAF109"
+  | "GRAF110"
   | "GRAF111"
   | "GRAF112"
   | "GRAF113"
@@ -73,6 +75,10 @@ export interface GrafanaArtifacts {
   providers?: Array<Record<string, unknown>>;
   /** Alerting provisioning files (rule groups, contact points, policies, mute timings, templates). */
   alerting?: AlertingDoc[];
+  /** The folders the build resolved (its index's `folders`): each level of each dashboard's folder path, and every `Folder`. */
+  folders?: Array<{ uid: string; title: string; path?: string; parentUid?: string }>;
+  /** `deleteDatasources` entries of datasource provisioning files. */
+  deleteDatasources?: Array<{ name: string; orgId?: number }>;
 }
 
 export type { AlertingDoc };
@@ -180,6 +186,19 @@ export function checkDatasourceRefs(a: GrafanaArtifacts): GrafanaIssue[] {
       }
     }
 
+    // An ExternalDatasource the provisioning file deletes (and does not provision again) is gone once Grafana provisions it.
+    const deleted = new Set((a.deleteDatasources ?? []).filter((x) => (x.orgId ?? 1) === 1).map((x) => x.name));
+    const provisioned = new Set(a.datasources.map((x) => x.name));
+    const gone = new Set([...known.values()].filter((k) => k.external && k.name !== undefined && deleted.has(k.name) && !provisioned.has(k.name)).map((k) => k.uid));
+    for (const { where, resolved } of uses) {
+      if (resolved.kind !== "declared" || !gone.has(resolved.datasource.uid)) continue;
+      push(
+        "GRAF101",
+        "error",
+        `${where} uses external datasource "${resolved.datasource.name}", which the datasource provisioning file deletes (deleteDatasources); Grafana removes it before the dashboard can use it.`,
+      );
+    }
+
     // A datasource variable offers the datasources of its plugin type; with none declared it has nothing to choose.
     if (known.size > 0) {
       for (const v of dsVariables) {
@@ -225,10 +244,22 @@ export function checkVariables(a: GrafanaArtifacts): GrafanaIssue[] {
       }
     }
     for (const v of variablesOf(d)) {
+      const ref = v.datasource as DatasourceRefJson | undefined;
+      if (ref && typeof ref === "object" && isVariableUid(ref.uid)) {
+        for (const n of variableReferences(ref.uid!)) if (n !== v.name) report(n, `variable "${String(v.name)}" datasource`);
+      }
       if (v.type !== "query") continue;
-      const names = new Set(stringsIn(v.query, new Set()).flatMap(variableReferences));
+      const names = new Set(stringsIn(v.query, new Set(["refId"])).flatMap(variableReferences));
       for (const n of names) if (n !== v.name) report(n, `variable "${String(v.name)}" query`);
     }
+    for (const an of annotationsOf(d)) {
+      const where = `annotation "${String(an.name ?? "?")}"`;
+      const ref = an.datasource as DatasourceRefJson | undefined;
+      if (ref && typeof ref === "object" && isVariableUid(ref.uid)) for (const n of variableReferences(ref.uid!)) report(n, `${where} datasource`);
+      // Grafana interpolates the query (`target`, or Prometheus's legacy `expr`), not the name, colour or title formats.
+      const names = new Set(stringsIn([an.target, an.expr], TARGET_SKIP).flatMap(variableReferences));
+      for (const n of names) report(n, `${where} query`);
+    }
   }
   return issues;
 }
@@ -253,6 +284,10 @@ export function checkDuplicates(a: GrafanaArtifacts): GrafanaIssue[] {
   const allUids = [...a.datasources.map((d) => d.uid), ...(a.externalDatasources ?? []).map((d) => d.uid)];
   for (const [uid, n] of dupes(allUids, (u) => u)) push(`${n} datasources share the uid "${uid}".`, uid);
   for (const [name, n] of dupes(a.datasources, (d) => d.name)) push(`${n} datasources share the name "${name}"; Grafana needs names to be unique.`, name);
+  for (const [uid, n] of dupes(a.folders ?? [], (f) => f.uid)) {
+    const paths = (a.folders ?? []).filter((f) => f.uid === uid).map((f) => `"${f.path ?? f.title}"`);
+    push(`${n} folders share the uid "${uid}" (${paths.join(", ")}); Grafana keeps one folder per uid, so the API applier refuses the build. Give one a Folder with its own uid.`, uid);
+  }
   for (const { json: d } of a.dashboards) {
     const uid = String(d.uid ?? "");
     const panels = panelsOf(d).map((p) => p.panel);
@@ -355,6 +390,19 @@ export function checkIdentity(a: GrafanaArtifacts): GrafanaIssue[] {
       });
     }
   }
+  for (const f of a.folders ?? []) {
+    const where = `Folder "${f.path ?? f.title}"`;
+    if (!isValidUid(f.uid)) {
+      issues.push({ code: "GRAF106", severity: "error", message: `${where} has uid "${f.uid}"; Grafana accepts 1-40 letters, digits, "-" and "_".`, entity: f.uid });
+    } else if (f.uid === "general") {
+      issues.push({
+        code: "GRAF106",
+        severity: "error",
+        message: `${where} has uid "general", which Grafana keeps for its root (the General folder) and refuses for a folder. Leave folder out to put a dashboard in General, or give the folder another uid.`,
+        entity: f.uid,
+      });
+    }
+  }
   for (const ds of a.externalDatasources ?? []) {
     if (!isValidUid(ds.uid)) {
       issues.push({
@@ -377,6 +425,11 @@ export function checkIdentity(a: GrafanaArtifacts): GrafanaIssue[] {
  */
 export function checkSchema(a: GrafanaArtifacts): GrafanaIssue[] {
   const issues: GrafanaIssue[] = [];
+  if (a.dashboards.length === 0) return issues;
+  const unavailable = schemaValidationUnavailable();
+  if (unavailable) {
+    return [{ code: "GRAF107", severity: "warning", message: `Dashboards were not checked against the Grafana schema: ${unavailable}.` }];
+  }
   for (const { json: d } of a.dashboards) {
     for (const p of validateDashboardSchema(d)) {
       issues.push({
@@ -412,6 +465,44 @@ export function checkPromqlSyntax(a: GrafanaArtifacts): GrafanaIssue[] {
   return issues;
 }
 
+// ── GRAF110: repeats ────────────────────────────────────────────
+
+/**
+ * A panel or row repeated over a variable Grafana cannot repeat over, or
+ * one that can only ever hold one value. Grafana repeats over a query,
+ * custom, datasource or group by variable (a `MultiValueVariable` in
+ * @grafana/scenes), once per selected value. Over any other kind it logs an
+ * error and shows the panel once; over a query, custom or datasource
+ * variable with neither `multi` nor `includeAll`, there is only ever one
+ * value to repeat for. A repeat naming no variable is GRAF103's.
+ */
+const KIND_NAMES: Readonly<Record<string, string>> = { adhoc: "an ad hoc", interval: "an interval", groupby: "a group by" };
+
+export function checkRepeats(a: GrafanaArtifacts): GrafanaIssue[] {
+  const issues: GrafanaIssue[] = [];
+  for (const { json: d } of a.dashboards) {
+    const variables = new Map(variablesOf(d).map((v) => [String(v.name), v]));
+    for (const { panel } of panelsOf(d)) {
+      if (typeof panel.repeat !== "string" || panel.repeat === "") continue;
+      const v = variables.get(panel.repeat);
+      if (!v) continue;
+      const where = panel.type === "row" ? `row "${String(panel.title ?? "")}"` : describePanel(panel);
+      const type = String(v.type);
+      const kind = `${KIND_NAMES[type] ?? `a ${type}`} variable`;
+      let why: string | undefined;
+      if (!MULTI_VALUE_KINDS.has(type)) {
+        why = `${kind}, which Grafana cannot repeat over: it shows the ${panel.type === "row" ? "row" : "panel"} once. Repeat over a query, custom, datasource or group by variable`;
+      } else if (type !== "groupby" && v.multi !== true && v.includeAll !== true) {
+        why = `${kind} with neither multi nor includeAll, so it only ever holds one value and the ${panel.type === "row" ? "row" : "panel"} shows once. Set multi or includeAll on it`;
+      }
+      if (why) {
+        issues.push({ code: "GRAF110", severity: "warning", message: `${dashName(d)} ${where} repeats over $${panel.repeat}, ${why}.`, entity: String(d.uid ?? "") });
+      }
+    }
+  }
+  return issues;
+}
+
 // ── GRAF115: units ──────────────────────────────────────────────
 
 /** Every unit a panel sets, with where: field defaults, `unit` overrides, heatmap axes and cells, and a legacy graph panel's y-axes. */
@@ -593,6 +684,7 @@ const BY_CODE: Record<GrafanaIssueCode, (a: GrafanaArtifacts) => GrafanaIssue[]>
   GRAF107: checkSchema,
   GRAF108: checkPromqlSyntax,
   GRAF109: checkProvisioning,
+  GRAF110: checkRepeats,
   GRAF111: (a) => checkRuleQueries(a.alerting ?? []),
   GRAF112: (a) => checkRuleDatasources(a.alerting ?? [], knownDatasourcesOf(a)),
   GRAF113: (a) => checkNotificationRefs(a.alerting ?? []),

package/src/validate.ts

@@ -25,6 +25,8 @@ export const REQUIRED_NAMES = [
   "Datasource",
   "ExternalDatasource",
   "DashboardProvider",
+  "DatasourceProvisioning",
+  "Folder",
   "Row",
   "TimeSeriesPanel",
   "StatPanel",
@@ -50,12 +52,24 @@ export const REQUIRED_NAMES = [
   "PromQuery",
   "TempoQuery",
   "LokiQuery",
+  "ElasticsearchQuery",
+  "CloudWatchQuery",
+  "AzureMonitorQuery",
+  "CloudMonitoringQuery",
+  "BigQueryQuery",
+  "PyroscopeQuery",
+  "PostgresQuery",
+  "MySQLQuery",
+  "MSSQLQuery",
   "QueryVariable",
   "CustomVariable",
   "IntervalVariable",
   "DatasourceVariable",
   "ConstantVariable",
   "TextboxVariable",
+  "AdhocVariable",
+  "GroupByVariable",
+  "SwitchVariable",
 ];
 
 const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));

package/src/validation.ts

@@ -0,0 +1,27 @@
+/**
+ * `@intentius/chant-lexicon-grafana/validation`: the GRAF101-GRAF115 checks
+ * as plain functions over built Grafana output, and the schema validation
+ * behind GRAF107, for code that checks dashboards without a build.
+ *
+ * These are not on the package root, so importing the lexicon to declare
+ * dashboards does not load them. `chant build` and `chant lint` run the same
+ * checks through the plugin's post-synth checks. ajv is loaded the first time
+ * a schema is checked, and the schemas come from a generated module rather
+ * than files, so this works bundled.
+ */
+
+export {
+  validateGrafanaOutput,
+  issuesFor,
+  knownDatasourcesOf,
+  type GrafanaIssue,
+  type GrafanaIssueCode,
+  type GrafanaArtifacts,
+  type DashboardDoc,
+} from "./validate-output";
+export {
+  validateDashboardSchema,
+  validateExpressionSchema,
+  schemaValidationUnavailable,
+  type SchemaProblem,
+} from "./schema-validate";

package/src/variables.ts

@@ -1,6 +1,6 @@
 /**
  * Dashboard variables (Grafana's "templating"): query, custom, interval,
- * datasource, constant and textbox.
+ * datasource, constant, textbox, ad hoc filters, group by and switch.
  *
  * A variable is declared on its own and listed in a dashboard's
  * `variables`. Queries reference it as `$name` or `${name}` in their
@@ -12,9 +12,12 @@
 import { createProperty } from "@intentius/chant/runtime";
 import type { Declarable } from "@intentius/chant/declarable";
 import type { DatasourceEntity, DatasourceRef, ExternalDatasourceEntity } from "./datasource";
-import type { VariableOption } from "./schema/dashboard.gen";
+import type { AdHocFilter, VariableOption } from "./schema/dashboard.gen";
 
-export type VariableKind = "query" | "custom" | "interval" | "datasource" | "constant" | "textbox";
+export type VariableKind = "query" | "custom" | "interval" | "datasource" | "constant" | "textbox" | "adhoc" | "groupby" | "switch";
+
+/** The kinds Grafana can repeat a panel or row over: the ones that hold a list of values (`MultiValueVariable` in @grafana/scenes). */
+export const MULTI_VALUE_KINDS: ReadonlySet<string> = new Set(["query", "custom", "datasource", "groupby"]);
 
 /** Where the variable shows: with its label, without it, or not at all. */
 export type VariableHide = "label" | "valueOnly" | "hidden";
@@ -42,10 +45,45 @@ interface MultiValueProps {
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type VariableDatasource = DatasourceEntity<any> | ExternalDatasourceEntity<any> | DatasourceRef | DatasourceVariableEntity<any>;
 
+/**
+ * A variable query in the object form a datasource's variable editor
+ * writes. Grafana passes it to the datasource as it is, so any key the
+ * datasource reads may be here.
+ */
+export interface VariableQueryObject {
+  /** The query text, when the datasource has one (Prometheus, Loki, and most others). */
+  query?: string;
+  /** The editor's id for the query; Grafana writes e.g. `PrometheusVariableQueryEditor-VariableQuery`. */
+  refId?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * A Prometheus variable query as Grafana's Prometheus variable editor
+ * writes it. `query` is the text Grafana runs (`label_values(up, job)`);
+ * the other fields let the editor show the query in its form again.
+ */
+export interface PrometheusVariableQuery extends VariableQueryObject {
+  query: string;
+  /** The editor's query type: 0 label names, 1 label values, 2 metrics, 3 query result, 4 series query, 5 classic query. */
+  qryType?: 0 | 1 | 2 | 3 | 4 | 5;
+  label?: string;
+  metric?: string;
+  seriesQuery?: string;
+  varQueryResult?: string;
+  labelFilters?: Array<{ label: string; op: string; value: string }>;
+}
+
 export interface QueryVariableProps extends CommonVariableProps, MultiValueProps {
   datasource: VariableDatasource;
-  /** The datasource's variable query, e.g. `label_values(up, job)` for Prometheus. */
-  query: string;
+  /**
+   * The datasource's variable query: a string (`label_values(up, job)` for
+   * Prometheus), or the object the datasource's variable editor writes
+   * (`{ query: "label_values(up, job)", qryType: 1 }`).
+   */
+  query: string | VariableQueryObject;
+  /** The text Grafana shows for the query in the variable list. Defaults to the query string. */
+  definition?: string;
   regex?: string;
   /** When to re-run the query. Defaults to on dashboard load. */
   refresh?: "never" | "onLoad" | "onTimeRangeChange";
@@ -85,6 +123,51 @@ export interface TextboxVariableProps extends CommonVariableProps {
   value?: string;
 }
 
+/** One ad hoc filter: `key operator value`, e.g. `{ key: "namespace", operator: "=", value: "shop" }`. */
+export type AdhocFilter = AdHocFilter;
+
+/** A key an ad hoc or group by variable offers, in place of asking the datasource. */
+export interface VariableKeyOption {
+  text: string;
+  value?: string | number;
+  [key: string]: unknown;
+}
+
+export interface AdhocVariableProps extends CommonVariableProps {
+  /** The datasource whose queries get the filters, and which is asked for keys and values. */
+  datasource: VariableDatasource;
+  /** The filters applied when the dashboard loads. */
+  filters?: AdhocFilter[];
+  /** Filters that narrow the key and value lookups, not shown or applied to queries. */
+  baseFilters?: AdhocFilter[];
+  /** A fixed set of keys to offer instead of the datasource's. */
+  defaultKeys?: VariableKeyOption[];
+  /** Whether a key or value not in the list can be typed in. Grafana's default is true. */
+  allowCustomValue?: boolean;
+  /** Offer the group-by operator in the filter box (Grafana 13, behind the `dashboardUnifiedDrilldownControls` feature toggle). */
+  enableGroupBy?: boolean;
+}
+
+export interface GroupByVariableProps extends CommonVariableProps {
+  /** The datasource whose queries are grouped, and which is asked for the keys. */
+  datasource: VariableDatasource;
+  /** A fixed set of keys to offer instead of the datasource's: a key, or `{ text, value }`. */
+  options?: Array<string | { text: string; value: string }>;
+  /** The keys selected when the dashboard loads with none in the URL. */
+  defaultValue?: string[] | VariableOption;
+  /** Whether a key not in the list can be typed in. Grafana's default is true. */
+  allowCustomValue?: boolean;
+}
+
+export interface SwitchVariableProps extends Omit<CommonVariableProps, "current"> {
+  /** Whether the switch is on when the dashboard loads. Defaults to off. */
+  enabled?: boolean;
+  /** The value `$name` has when the switch is on. Defaults to `"true"`. */
+  enabledValue?: string;
+  /** The value `$name` has when the switch is off. Defaults to `"false"`. */
+  disabledValue?: string;
+}
+
 export interface VariableEntity<P = CommonVariableProps> extends Declarable {
   readonly props: P;
   readonly variableKind: VariableKind;
@@ -99,7 +182,7 @@ export interface DatasourceVariableEntity<T extends string = string> extends Var
 
 export const VARIABLE_TYPE_PREFIX = "Grafana::Variable::";
 
-function variableClass<P extends CommonVariableProps | ConstantVariableProps>(kind: VariableKind, className: string) {
+function variableClass<P extends CommonVariableProps | ConstantVariableProps | SwitchVariableProps>(kind: VariableKind, className: string) {
   const Base = createProperty(`${VARIABLE_TYPE_PREFIX}${kind}`, "grafana") as unknown as (this: object, props: Record<string, unknown>) => void;
   const Cls = function (this: object, props: P) {
     Base.call(this, props as unknown as Record<string, unknown>);
@@ -143,6 +226,30 @@ export const TextboxVariable = variableClass<TextboxVariableProps>("textbox", "T
   props: TextboxVariableProps,
 ) => VariableEntity<TextboxVariableProps>;
 
+/**
+ * Ad hoc filters: `key operator value` filters Grafana adds to every query
+ * sent to the variable's datasource (Prometheus, Loki, Elasticsearch,
+ * InfluxDB and others whose plugin supports them). Referenced by no query.
+ */
+export const AdhocVariable = variableClass<AdhocVariableProps>("adhoc", "AdhocVariable") as unknown as new (
+  props: AdhocVariableProps,
+) => VariableEntity<AdhocVariableProps>;
+
+/**
+ * Group by: a choice of label keys Grafana adds as a grouping to every query
+ * sent to the variable's datasource. In Grafana 12.4 and 13.x it is
+ * experimental: with the `groupByVariable` feature toggle off, Grafana
+ * drops it when the dashboard loads.
+ */
+export const GroupByVariable = variableClass<GroupByVariableProps>("groupby", "GroupByVariable") as unknown as new (
+  props: GroupByVariableProps,
+) => VariableEntity<GroupByVariableProps>;
+
+/** An on/off switch, `$name` being `enabledValue` or `disabledValue`. New in Grafana 12.3. */
+export const SwitchVariable = variableClass<SwitchVariableProps>("switch", "SwitchVariable") as unknown as new (
+  props: SwitchVariableProps,
+) => VariableEntity<SwitchVariableProps>;
+
 export function isVariableEntity(value: unknown): value is VariableEntity {
   return (
     typeof value === "object" &&