@intentius/chant-lexicon-grafana 0.97.0 → 0.99.0

package/src/datasource-refs.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, test } from "vitest";
+import { datasourceUses, knownDatasources, resolveDatasourceRef } from "./datasource-refs";
+
+const known = knownDatasources([{ name: "Prometheus", type: "prometheus", uid: "prom" }], [{ type: "loki", uid: "logs", name: "Logs" }]);
+
+function dashboard(panels: unknown[], variables: unknown[] = []) {
+  return { uid: "d", title: "D", panels, templating: { list: variables } };
+}
+
+describe("resolveDatasourceRef", () => {
+  const vars = new Map([["ds", { type: "datasource", name: "ds", query: "prometheus" }]]);
+
+  test("resolves provisioned and external datasources to their plugin type", () => {
+    expect(resolveDatasourceRef({ uid: "prom" }, vars, known)).toMatchObject({ kind: "declared", type: "prometheus", datasource: { external: false } });
+    expect(resolveDatasourceRef({ type: "loki", uid: "logs" }, vars, known)).toMatchObject({ kind: "declared", type: "loki", datasource: { external: true, name: "Logs" } });
+  });
+
+  test("resolves a datasource variable to its plugin type", () => {
+    expect(resolveDatasourceRef({ uid: "${ds}" }, vars, known)).toEqual({ kind: "variable", variable: "ds", declared: true, type: "prometheus" });
+    expect(resolveDatasourceRef({ type: "tempo", uid: "$other" }, vars, known)).toEqual({ kind: "variable", variable: "other", declared: false, type: "tempo" });
+  });
+
+  test("separates Grafana's pseudo-datasources, unknown uids and no ref", () => {
+    expect(resolveDatasourceRef({ type: "datasource", uid: "-- Mixed --" }, vars, known).kind).toBe("builtin");
+    expect(resolveDatasourceRef({ type: "prometheus", uid: "gone" }, vars, known)).toEqual({ kind: "undeclared", uid: "gone", type: "prometheus" });
+    expect(resolveDatasourceRef(undefined, vars, known)).toEqual({ kind: "default" });
+    expect(resolveDatasourceRef({ type: "prometheus" }, vars, known)).toEqual({ kind: "default", type: "prometheus" });
+  });
+});
+
+describe("datasourceUses", () => {
+  test("a query without its own ref goes where its panel's goes", () => {
+    const d = dashboard([{ type: "stat", id: 1, title: "p", datasource: { uid: "prom" }, targets: [{ refId: "A", expr: "up" }, { refId: "B", datasource: { uid: "logs" } }] }]);
+    const queries = datasourceUses(d, known).filter((u) => u.kind === "query");
+    expect(queries.map((u) => [u.target?.refId, u.ref === undefined, u.resolved.type])).toEqual([
+      ["A", true, "prometheus"],
+      ["B", false, "loki"],
+    ]);
+  });
+
+  test("a query under a -- Mixed -- panel with no ref goes to the default datasource", () => {
+    const d = dashboard([{ type: "table", id: 1, datasource: { type: "datasource", uid: "-- Mixed --" }, targets: [{ refId: "A" }] }]);
+    expect(datasourceUses(d, known).find((u) => u.kind === "query")?.resolved).toEqual({ kind: "default" });
+  });
+
+  test("covers panels in collapsed rows and query variables, and skips rows", () => {
+    const d = dashboard(
+      [{ type: "row", id: 1, collapsed: true, datasource: { uid: "prom" }, panels: [{ type: "stat", id: 2, datasource: { uid: "logs" }, targets: [] }] }],
+      [{ type: "query", name: "job", datasource: { uid: "prom" }, query: "label_values(job)" }],
+    );
+    expect(datasourceUses(d, known).map((u) => [u.kind, u.where, u.resolved.type])).toEqual([
+      ["panel", 'panel (untitled) (id 2)', "loki"],
+      ["variable", 'variable "job"', "prometheus"],
+    ]);
+  });
+});

package/src/datasource-refs.ts

@@ -0,0 +1,189 @@
+/**
+ * Which datasource each panel, query and query variable in built dashboard
+ * JSON sends its request to.
+ *
+ * GRAF101 and GRAF102 use this to check references against the datasources
+ * a build knows about: the ones it provisions (`Datasource`) and the ones it
+ * only references (`ExternalDatasource`). Any other check that needs to know
+ * which plugin runs a query (a PromQL syntax check only wants the queries
+ * that reach a Prometheus) can call `datasourceUses()` and read
+ * `resolved.type`.
+ */
+
+import type { ExternalDatasourceRecord, ProvisionedDatasource } from "./build";
+import { BUILTIN_DATASOURCE_UIDS } from "./datasource";
+
+type Json = Record<string, unknown>;
+
+/** A `{ type, uid }` datasource reference as dashboard JSON holds it. */
+export interface DatasourceRefJson {
+  type?: string;
+  uid?: string;
+}
+
+/** A datasource the build knows by uid: provisioned by it, or declared external. */
+export interface KnownDatasource {
+  uid: string;
+  type: string;
+  name?: string;
+  /** Declared with `ExternalDatasource`: referenced, not provisioned. */
+  external: boolean;
+}
+
+/**
+ * Where a reference leads.
+ *
+ * - `declared`: a known datasource; `type` is its plugin type.
+ * - `variable`: a `${name}` uid; `type` is the datasource variable's plugin type, else the ref's own.
+ * - `builtin`: one of Grafana's pseudo-datasources (`-- Mixed --`, `-- Dashboard --`, `grafana`).
+ * - `undeclared`: a uid the build does not know; `type` is whatever the ref says.
+ * - `default`: no uid, so Grafana picks its default datasource; `type` is the ref's, if it has one.
+ */
+export type ResolvedDatasource =
+  | { kind: "declared"; type: string; datasource: KnownDatasource }
+  | { kind: "variable"; type?: string; variable: string; declared: boolean }
+  | { kind: "builtin"; type?: string }
+  | { kind: "undeclared"; type?: string; uid: string }
+  | { kind: "default"; type?: string };
+
+/** One place a dashboard names, or inherits, a datasource. */
+export interface DatasourceUse {
+  /** A panel's own `datasource`, one of its queries (`targets`), or a query variable. */
+  kind: "panel" | "query" | "variable";
+  /** A human description, e.g. `panel "Latency" (id 3) query B`. */
+  where: string;
+  panel?: Json;
+  target?: Json;
+  variable?: Json;
+  /** The ref written on this panel, query or variable; unset when a query inherits its panel's. */
+  ref?: DatasourceRefJson;
+  /** Where the request goes: the query's own ref, else its panel's. */
+  resolved: ResolvedDatasource;
+}
+
+/** Every datasource a build knows by uid. A provisioned one wins over an external one of the same uid (GRAF104 reports the clash). */
+export function knownDatasources(
+  datasources: readonly ProvisionedDatasource[],
+  external: readonly ExternalDatasourceRecord[] = [],
+): Map<string, KnownDatasource> {
+  const out = new Map<string, KnownDatasource>();
+  for (const d of external) out.set(d.uid, { uid: d.uid, type: d.type, ...(d.name ? { name: d.name } : {}), external: true });
+  for (const d of datasources) out.set(d.uid, { uid: d.uid, type: d.type, name: d.name, external: false });
+  return out;
+}
+
+export interface PanelInfo {
+  panel: Json;
+  /** Panels inside a collapsed row are laid out in their own group. */
+  group: string;
+}
+
+/** Every panel of a dashboard, including those inside collapsed rows, and the rows themselves. */
+export function panelsOf(dashboard: Json): PanelInfo[] {
+  const out: PanelInfo[] = [];
+  const top = Array.isArray(dashboard.panels) ? (dashboard.panels as Json[]) : [];
+  for (const p of top) {
+    if (!p || typeof p !== "object") continue;
+    out.push({ panel: p, group: "" });
+    if (p.type === "row" && Array.isArray(p.panels)) {
+      for (const c of p.panels as Json[]) if (c && typeof c === "object") out.push({ panel: c, group: `row ${String(p.id)}` });
+    }
+  }
+  return out;
+}
+
+export function describePanel(panel: Json): string {
+  const title = typeof panel.title === "string" && panel.title ? `"${panel.title}"` : "(untitled)";
+  return `panel ${title} (id ${String(panel.id ?? "?")})`;
+}
+
+/** A dashboard's `templating.list`. */
+export function variablesOf(dashboard: Json): Json[] {
+  const list = (dashboard.templating as { list?: unknown } | undefined)?.list;
+  return Array.isArray(list) ? (list as Json[]).filter((v) => v && typeof v === "object") : [];
+}
+
+const VAR_REF = /\$\{([A-Za-z_][A-Za-z0-9_]*)(?::[^}]*)?\}|\[\[([A-Za-z_][A-Za-z0-9_]*)(?::[^\]]*)?\]\]|\$([A-Za-z_][A-Za-z0-9_]*)/g;
+
+/** Every variable name referenced in a string. */
+export function variableReferences(text: string): string[] {
+  const out: string[] = [];
+  for (const m of text.matchAll(VAR_REF)) out.push(m[1] ?? m[2] ?? m[3]);
+  return out;
+}
+
+function refOf(value: unknown): DatasourceRefJson | undefined {
+  return value && typeof value === "object" && !Array.isArray(value) ? (value as DatasourceRefJson) : undefined;
+}
+
+/** Grafana's own pseudo-datasources, which no build declares. */
+export function isPseudoRef(ref: DatasourceRefJson): boolean {
+  return ref.type === "datasource" || ref.type === "grafana" || (ref.uid !== undefined && BUILTIN_DATASOURCE_UIDS.has(ref.uid));
+}
+
+/** The datasource variables of a dashboard, by name. */
+function datasourceVariables(dashboard: Json): Map<string, Json> {
+  return new Map(variablesOf(dashboard).filter((v) => v.type === "datasource").map((v) => [String(v.name), v]));
+}
+
+/** Where one reference leads, given the dashboard's datasource variables and the known datasources. */
+export function resolveDatasourceRef(
+  ref: DatasourceRefJson | undefined,
+  dsVariables: ReadonlyMap<string, Json>,
+  known: ReadonlyMap<string, KnownDatasource>,
+): ResolvedDatasource {
+  if (!ref || (ref.uid === undefined && ref.type === undefined)) return { kind: "default" };
+  if (isPseudoRef(ref)) return { kind: "builtin", ...(ref.type ? { type: ref.type } : {}) };
+  if (ref.uid === undefined) return { kind: "default", ...(ref.type ? { type: ref.type } : {}) };
+  if (ref.uid.includes("$")) {
+    const [name] = variableReferences(ref.uid);
+    const v = name ? dsVariables.get(name) : undefined;
+    const type = v && typeof v.query === "string" && v.query ? v.query : ref.type;
+    return { kind: "variable", variable: name ?? ref.uid, declared: v !== undefined, ...(type ? { type } : {}) };
+  }
+  const datasource = known.get(ref.uid);
+  if (datasource) return { kind: "declared", type: datasource.type, datasource };
+  return { kind: "undeclared", uid: ref.uid, ...(ref.type ? { type: ref.type } : {}) };
+}
+
+/**
+ * Every place a dashboard names or inherits a datasource: each panel's own
+ * ref, each query (with its own ref, or its panel's when it has none), and
+ * each query variable. Rows are left out; their panels carry the ref.
+ */
+export function datasourceUses(dashboard: Json, known: ReadonlyMap<string, KnownDatasource>): DatasourceUse[] {
+  const dsVars = datasourceVariables(dashboard);
+  const out: DatasourceUse[] = [];
+  for (const { panel } of panelsOf(dashboard)) {
+    if (panel.type === "row") continue;
+    const panelRef = refOf(panel.datasource);
+    if (panelRef) out.push({ kind: "panel", where: describePanel(panel), panel, ref: panelRef, resolved: resolveDatasourceRef(panelRef, dsVars, known) });
+    // A query under a `-- Mixed --` panel with no ref of its own goes to the default datasource.
+    const inherited = panelRef && panelRef.uid !== "-- Mixed --" ? panelRef : undefined;
+    const targets = Array.isArray(panel.targets) ? (panel.targets as Json[]) : [];
+    for (const target of targets) {
+      if (!target || typeof target !== "object") continue;
+      const own = refOf(target.datasource);
+      out.push({
+        kind: "query",
+        where: `${describePanel(panel)} query ${String(target.refId ?? "?")}`,
+        panel,
+        target,
+        ...(own ? { ref: own } : {}),
+        resolved: resolveDatasourceRef(own ?? inherited, dsVars, known),
+      });
+    }
+  }
+  for (const variable of variablesOf(dashboard)) {
+    if (variable.type !== "query") continue;
+    const ref = refOf(variable.datasource);
+    out.push({
+      kind: "variable",
+      where: `variable "${String(variable.name)}"`,
+      variable,
+      ...(ref ? { ref } : {}),
+      resolved: resolveDatasourceRef(ref, dsVars, known),
+    });
+  }
+  return out;
+}

package/src/datasource.ts

@@ -83,6 +83,58 @@ export function isDatasourceEntity(value: unknown): value is DatasourceEntity {
   );
 }
 
+export const EXTERNAL_DATASOURCE_TYPE = "Grafana::ExternalDatasource";
+
+export interface ExternalDatasourceProps<T extends string = string> {
+  /** The datasource plugin id, e.g. `prometheus`. */
+  type: T;
+  /** The uid the datasource already has in Grafana. */
+  uid: string;
+  /** Its display name in Grafana, for messages and for a `DatasourceVariable` `regex`. */
+  name?: string;
+}
+
+export interface ExternalDatasourceEntity<T extends string = string> extends Declarable {
+  readonly props: ExternalDatasourceProps<T>;
+  /** The plugin id. */
+  readonly datasourceType: T;
+  /** The uid panels will reference. */
+  readonly uid: string;
+}
+
+const ExternalBase = createResource(EXTERNAL_DATASOURCE_TYPE, "grafana", {}) as unknown as (this: object, props: Record<string, unknown>) => void;
+
+export interface ExternalDatasourceConstructor {
+  new <T extends string>(props: ExternalDatasourceProps<T>): ExternalDatasourceEntity<T>;
+}
+
+/**
+ * A datasource that already exists in Grafana: provisioned by hand, by
+ * another build root, or by another tool. It is never written to the
+ * provisioning file. Panels, queries and variables use it like a
+ * `Datasource`, and GRAF101/GRAF102 check references against it.
+ */
+export const ExternalDatasource = function (this: object, props: ExternalDatasourceProps) {
+  ExternalBase.call(this, props as unknown as Record<string, unknown>);
+  Object.defineProperty(this, "datasourceType", { value: props.type, enumerable: false });
+  Object.defineProperty(this, "uid", { value: props.uid, enumerable: false });
+} as unknown as ExternalDatasourceConstructor;
+Object.defineProperty(ExternalDatasource, "name", { value: "ExternalDatasource" });
+
+export function isExternalDatasource(value: unknown): value is ExternalDatasourceEntity {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as Declarable).entityType === EXTERNAL_DATASOURCE_TYPE &&
+    (value as Declarable).lexicon === "grafana"
+  );
+}
+
+/** A declared or an external datasource: anything a panel can hold that has a fixed uid. */
+export function isDatasourceDeclaration(value: unknown): value is DatasourceEntity | ExternalDatasourceEntity {
+  return isDatasourceEntity(value) || isExternalDatasource(value);
+}
+
 /** A datasource declared somewhere this build can't see, named by its Grafana ref. */
 export interface DatasourceRef<T extends string = string> {
   type: T;

package/src/deep-observe-hooks.ts

@@ -0,0 +1,252 @@
+/**
+ * grafana deep-observation noise rules (#2946).
+ *
+ * Plain data on the plugin, because core applies the same rules to the
+ * declared tree (a `Dashboard`'s props, panels and queries inlined), which
+ * no reader touches. The live tree is the stored dashboard put back into the
+ * same vocabulary by the importer (./import/live-export.ts), so what is left
+ * to name here is what the translation cannot decide: values the build
+ * wrote that the author did not, values Grafana adds or drops on save, and
+ * values an author wrote out that are also what happens when they are left
+ * out.
+ *
+ * Measured against Grafana 12.4.11 and 13.2.2 (the e2e in
+ * ./observe.e2e.test.ts): read over `/api/dashboards/uid`, a stored dashboard
+ * differs from the built one only by the `id` and `version` Grafana adds
+ * (../test/e2e/stored-model.ts). Read over `/apis/dashboard.grafana.app`, its
+ * spec has no `id` or `version`, but it carries the built-in "Annotations &
+ * Alerts" annotation, and empty `options` and `fieldConfig` and every `null`
+ * are gone. The rest of this table is the build's own choices: panel ids,
+ * grid positions, query refIds, a panel's datasource taken from its queries.
+ *
+ * Every rule is one of four kinds, and they are in this order below:
+ *
+ * 1. **Never compared**, on either side: Grafana's bookkeeping.
+ * 2. **Empty is absent**, on both sides: `null`, `{}` and `[]` mean the same
+ *    as leaving a key out, everywhere in a dashboard or datasource. The cost
+ *    is that values added where the declaration wrote `[]` are reported as
+ *    unclaimed rather than as drift.
+ * 3. **Build-derived**, on the live side where the declaration has nothing:
+ *    the build filled it in, so it cannot disagree with what was declared.
+ * 4. **Default written out**, on the declared side where the live side has
+ *    nothing: the author wrote the value Grafana assumes, which the
+ *    translation leaves out.
+ *
+ * Rules 3 and 4 are gated on `counterpart === "absent"`, so a value the
+ * author did declare is always compared, and a change away from it is drift.
+ * (That relies on core walking a panel's props when it lists the declared
+ * paths, which #2946 fixed in `deepPathSet`.)
+ */
+
+import type { DeepArrayElement, DeepNode, DeepNormalizationHooks } from "@intentius/chant/deep-observation";
+import { DASHBOARD_TYPE } from "./dashboard";
+import { DATASOURCE_TYPE, EXTERNAL_DATASOURCE_TYPE } from "./datasource";
+import { registeredQueries } from "./query";
+import { DASHBOARD_SCHEMA_VERSION } from "./schema/dashboard.gen";
+import { BOOKKEEPING_KEYS, LINK_DEFAULTS, deepEqual, isBuiltinAnnotation } from "./import/normalize";
+import { DATASOURCE_API_DEFAULTS } from "./import/live-export";
+
+type Json = Record<string, unknown>;
+
+/** Where a node sits in a dashboard tree, from its index-erased pattern. */
+type Level = "dashboard" | "panel" | "target" | "variable" | "link";
+
+const SEGMENT = "([^.\\[\\]]+)";
+const PANEL = "panels\\[\\](?:\\.panels\\[\\])?";
+const LEVELS: ReadonlyArray<[Level, RegExp]> = [
+  ["dashboard", new RegExp(`^${SEGMENT}$`)],
+  ["panel", new RegExp(`^${PANEL}\\.${SEGMENT}$`)],
+  ["target", new RegExp(`^${PANEL}\\.targets\\[\\]\\.${SEGMENT}$`)],
+  ["variable", new RegExp(`^variables\\[\\]\\.${SEGMENT}$`)],
+  ["link", new RegExp(`^(?:${PANEL}\\.)?links\\[\\]\\.${SEGMENT}$`)],
+];
+
+function levelOf(pattern: string): { level: Level; key: string } | undefined {
+  for (const [level, re] of LEVELS) {
+    const m = re.exec(pattern);
+    if (m) return { level, key: m[1] };
+  }
+  return undefined;
+}
+
+/**
+ * Defaults in the props vocabulary: a key an author may write at this value,
+ * and the translation leaves out because Grafana assumes it. The dashboard
+ * and panel entries mirror `DASHBOARD_DEFAULTS` and `PANEL_DEFAULTS` in
+ * ./import/normalize.ts, with `graphTooltip` spelled as `Dashboard` takes it.
+ */
+export const PROP_DEFAULTS: Readonly<Record<Level, Readonly<Json>>> = {
+  dashboard: {
+    editable: true,
+    fiscalYearStartMonth: 0,
+    graphTooltip: "default",
+    links: [],
+    tags: [],
+    time: { from: "now-6h", to: "now" },
+    timepicker: {},
+    timezone: "",
+    weekStart: "",
+    refresh: "",
+    liveNow: false,
+    description: "",
+    schemaVersion: DASHBOARD_SCHEMA_VERSION,
+  },
+  panel: {
+    title: "",
+    description: "",
+    options: {},
+    targets: [],
+    transformations: [],
+    links: [],
+    transparent: false,
+    hideTimeOverride: false,
+    repeatDirection: "h",
+    // A row's.
+    collapsed: false,
+    panels: [],
+  },
+  target: {},
+  variable: {
+    label: "",
+    description: "",
+    hide: "label",
+    skipUrlSync: false,
+    multi: false,
+    includeAll: false,
+    allValue: "",
+    regex: "",
+    sort: 0,
+    refresh: "onLoad",
+    auto: false,
+    autoCount: 30,
+    autoMin: "10s",
+  },
+  link: LINK_DEFAULTS,
+};
+
+/**
+ * Keys the build fills in when a declaration leaves them out, by level:
+ * the dashboard's uid (from its export name) and schema version, a panel's
+ * id, grid position and datasource (from its queries), a query's refId.
+ * Grafana keeps what the build wrote, so undeclared, they read back as the
+ * build's choice rather than as anybody's edit.
+ *
+ * `timezone` is here as a value, not a key: chant writes `browser` for a
+ * dashboard that names none, where Grafana's own default is `""`.
+ */
+export const BUILD_DERIVED: Readonly<Record<Level, ReadonlySet<string>>> = {
+  dashboard: new Set(["uid", "schemaVersion"]),
+  panel: new Set(["id", "gridPos", "datasource", "pluginVersion"]),
+  target: new Set(["refId", "datasource"]),
+  // A query variable's selection is whatever the viewer last saved; the build writes one only when it is declared.
+  variable: new Set(["current", "datasource"]),
+  link: new Set(),
+};
+
+/** Defaults the build merges into a query from its class (`queryType: "traceql"`, `filters: []`): any key some class defaults, at that value. */
+function queryDefault(key: string, value: unknown): boolean {
+  for (const def of registeredQueries()) {
+    const defaults = (def as { defaults?: Json }).defaults;
+    if (defaults && key in defaults && deepEqual(defaults[key], value)) return true;
+  }
+  return false;
+}
+
+/** `[]` or a plain `{}`. Not a declarable, whose own keys are not enumerable. */
+function isEmptyContainer(value: unknown): boolean {
+  if (Array.isArray(value)) return value.length === 0;
+  if (typeof value !== "object" || value === null) return false;
+  const proto = Object.getPrototypeOf(value) as unknown;
+  return (proto === Object.prototype || proto === null) && Object.keys(value).length === 0;
+}
+
+function isEmptyFieldConfig(value: unknown): boolean {
+  return isEmptyContainer(value) || deepEqual(value, { defaults: {}, overrides: [] });
+}
+
+/** Any node at or under a `datasource` key: a reference, whichever form (ref, variable, entity) it takes. */
+function underDatasource(pattern: string): boolean {
+  return /(^|\.)datasource(\.|$)/.test(pattern);
+}
+
+function isDatasourceType(entityType: string): boolean {
+  return entityType === DATASOURCE_TYPE || entityType === EXTERNAL_DATASOURCE_TYPE;
+}
+
+function pruneDatasource(node: DeepNode): boolean {
+  // 1. The organisation is where it lives, not a property of it; the version is Grafana's save counter.
+  if (node.pattern === "orgId" || node.pattern === "version") return true;
+  // 2.
+  if (node.value === null || isEmptyContainer(node.value)) return true;
+  if (node.counterpart !== "absent") return false;
+  if (node.side === "live") {
+    // 3. The uid comes from the name when not declared; `editable` is `!readOnly`, true for one created in the UI or API.
+    return node.pattern === "uid" || node.pattern === "editable";
+  }
+  // 4.
+  if (node.pattern === "editable") return node.value === false;
+  return node.pattern in DATASOURCE_API_DEFAULTS && deepEqual(DATASOURCE_API_DEFAULTS[node.pattern], node.value);
+}
+
+function pruneDashboard(node: DeepNode): boolean {
+  const at = levelOf(node.pattern);
+
+  // 1. Bookkeeping and Grafana's own additions, whatever either side says.
+  if (at?.level === "dashboard" && BOOKKEEPING_KEYS.includes(at.key)) return true;
+  if (/^annotations(\.list)?\[\]$/.test(node.pattern) && isBuiltinAnnotation(node.value)) return true;
+  if (at?.level === "panel" && (at.key === "options" || at.key === "fieldConfig") && isEmptyFieldConfig(node.value)) return true;
+
+  // 2. Empty is absent, on both sides whatever the other has. Grafana drops
+  // every `null` when it stores a dashboard through /apis, and an empty list
+  // or object means what leaving the key out means. Not gated on the
+  // counterpart, which is matched by pattern: a threshold's first step has
+  // `value: null` where the others have a number, and one panel's
+  // `overrides: []` sits beside another's list of overrides.
+  if (node.value === null || isEmptyContainer(node.value)) return true;
+  if (node.counterpart !== "absent") return false;
+
+  if (node.side === "live") {
+    // 3. Build-derived.
+    if (underDatasource(node.pattern)) return true;
+    if (/^panels\[\](?:\.panels\[\])?\.gridPos\./.test(node.pattern)) return true;
+    if (!at) return false;
+    if (BUILD_DERIVED[at.level].has(at.key)) return true;
+    if (at.level === "dashboard" && at.key === "timezone" && node.value === "browser") return true;
+    if (at.level === "target" && queryDefault(at.key, node.value)) return true;
+    if (at.level === "link" && at.key in LINK_DEFAULTS && deepEqual(LINK_DEFAULTS[at.key], node.value)) return true;
+    return false;
+  }
+
+  // 4. A default written out.
+  if (!at) return false;
+  const defaults = PROP_DEFAULTS[at.level];
+  return at.key in defaults && deepEqual(defaults[at.key], node.value);
+}
+
+export const grafanaDeepNormalizationHooks: DeepNormalizationHooks = {
+  prune(node: DeepNode): boolean {
+    if (node.entityType === DASHBOARD_TYPE) return pruneDashboard(node);
+    if (isDatasourceType(node.entityType)) return pruneDatasource(node);
+    return false;
+  },
+
+  /**
+   * A datasource's secrets are compared by key, never by value: Grafana
+   * returns only which ones are set, the reader writes those as
+   * `[REDACTED]`, and the declared values (`$__env{...}` references, or
+   * worse) are masked the same way.
+   */
+  mask(node: DeepNode): boolean {
+    return isDatasourceType(node.entityType) && /^secureJsonData\./.test(node.pattern);
+  },
+
+  /**
+   * Dashboard tags are a set. Nothing else is reordered: panel order is
+   * layout order, and variable and link order is the order Grafana shows
+   * them in.
+   */
+  orderKey(element: DeepArrayElement): string | undefined {
+    if (element.entityType === DASHBOARD_TYPE && element.pattern === "tags" && typeof element.element === "string") return element.element;
+    return undefined;
+  },
+};