@intentius/chant-lexicon-grafana 0.96.0

package/src/schema/timeseries.gen.ts

@@ -0,0 +1,208 @@
+// Code generated by chant generate from the vendored Grafana schema
+// src/spec/schemas/timeseries.jsonschema.json (see src/pin.ts). DO NOT EDIT.
+/* eslint-disable */
+
+export interface Options {
+  timezone?: TimeZone[];
+  legend: VizLegendOptions;
+  tooltip: VizTooltipOptions;
+  orientation?: VizOrientation;
+}
+
+export type FieldConfig = GraphFieldConfig;
+
+/**
+ * A specific timezone from https://en.wikipedia.org/wiki/Tz_database
+ */
+export type TimeZone = string;
+
+/**
+ * TODO docs
+ */
+export interface VizLegendOptions {
+  displayMode: LegendDisplayMode;
+  placement: LegendPlacement;
+  showLegend: boolean;
+  asTable?: boolean;
+  isVisible?: boolean;
+  sortBy?: string;
+  sortDesc?: boolean;
+  width?: number;
+  calcs: string[];
+}
+
+/**
+ * TODO docs
+ */
+export interface VizTooltipOptions {
+  mode: TooltipDisplayMode;
+  sort: SortOrder;
+  maxWidth?: number;
+  maxHeight?: number;
+  hideZeros?: boolean;
+}
+
+/**
+ * TODO docs
+ */
+export type VizOrientation = "auto" | "vertical" | "horizontal";
+
+/**
+ * TODO docs
+ */
+export interface GraphFieldConfig {
+  drawStyle?: GraphDrawStyle;
+  gradientMode?: GraphGradientMode;
+  thresholdsStyle?: GraphThresholdsStyleConfig;
+  transform?: GraphTransform;
+  lineColor?: string;
+  lineWidth?: number;
+  lineInterpolation?: LineInterpolation;
+  lineStyle?: LineStyle;
+  fillColor?: string;
+  fillOpacity?: number;
+  showPoints?: VisibilityMode;
+  pointSize?: number;
+  pointColor?: string;
+  axisPlacement?: AxisPlacement;
+  axisColorMode?: AxisColorMode;
+  axisLabel?: string;
+  axisWidth?: number;
+  axisSoftMin?: number;
+  axisSoftMax?: number;
+  axisGridShow?: boolean;
+  scaleDistribution?: ScaleDistributionConfig;
+  axisCenteredZero?: boolean;
+  barAlignment?: BarAlignment;
+  barWidthFactor?: number;
+  stacking?: StackingConfig;
+  hideFrom?: HideSeriesConfig;
+  insertNulls?: boolean | number;
+  /**
+   * Indicate if null values should be treated as gaps or connected.
+   * When the value is a number, it represents the maximum delta in the
+   * X axis that should be considered connected.  For timeseries, this is milliseconds
+   */
+  spanNulls?: boolean | number;
+  fillBelowTo?: string;
+  pointSymbol?: string;
+  axisBorderShow?: boolean;
+  barMaxWidth?: number;
+}
+
+/**
+ * TODO docs
+ * Note: "hidden" needs to remain as an option for plugins compatibility
+ */
+export type LegendDisplayMode = "list" | "table" | "hidden";
+
+/**
+ * TODO docs
+ */
+export type LegendPlacement = "bottom" | "right";
+
+/**
+ * TODO docs
+ */
+export type TooltipDisplayMode = "single" | "multi" | "none";
+
+/**
+ * TODO docs
+ */
+export type SortOrder = "asc" | "desc" | "none";
+
+/**
+ * TODO docs
+ */
+export type GraphDrawStyle = "line" | "bars" | "points";
+
+/**
+ * TODO docs
+ */
+export type GraphGradientMode = "none" | "opacity" | "hue" | "scheme";
+
+/**
+ * TODO docs
+ */
+export interface GraphThresholdsStyleConfig {
+  mode: GraphThresholdsStyleMode;
+}
+
+/**
+ * TODO docs
+ */
+export type GraphTransform = "constant" | "negative-Y";
+
+/**
+ * TODO docs
+ */
+export type LineInterpolation = "linear" | "smooth" | "stepBefore" | "stepAfter";
+
+/**
+ * TODO docs
+ */
+export interface LineStyle {
+  fill?: "solid" | "dash" | "dot" | "square";
+  dash?: number[];
+}
+
+/**
+ * TODO docs
+ */
+export type VisibilityMode = "auto" | "never" | "always";
+
+/**
+ * TODO docs
+ */
+export type AxisPlacement = "auto" | "top" | "right" | "bottom" | "left" | "hidden";
+
+/**
+ * TODO docs
+ */
+export type AxisColorMode = "text" | "series";
+
+/**
+ * TODO docs
+ */
+export interface ScaleDistributionConfig {
+  type: ScaleDistribution;
+  log?: number;
+  linearThreshold?: number;
+}
+
+/**
+ * TODO docs
+ */
+export type BarAlignment = -1 | 0 | 1;
+
+/**
+ * TODO docs
+ */
+export interface StackingConfig {
+  mode?: StackingMode;
+  group?: string;
+}
+
+/**
+ * TODO docs
+ */
+export interface HideSeriesConfig {
+  tooltip: boolean;
+  legend: boolean;
+  viz: boolean;
+}
+
+/**
+ * TODO docs
+ */
+export type GraphThresholdsStyleMode = "off" | "line" | "dashed" | "area" | "line+area" | "dashed+area" | "series";
+
+/**
+ * TODO docs
+ */
+export type ScaleDistribution = "linear" | "log" | "ordinal" | "symlog";
+
+/**
+ * TODO docs
+ */
+export type StackingMode = "none" | "normal" | "percent";

package/src/schema-validate.ts

@@ -0,0 +1,143 @@
+/**
+ * Validate built Grafana JSON against the vendored schemas at
+ * `GRAFANA_SCHEMA_PIN`, offline.
+ *
+ * The dashboard is checked against the dashboard schema as it stands. Panel
+ * options, `fieldConfig.defaults.custom` and each query are checked against
+ * their plugin's schema with every `required` list removed, because Grafana
+ * fills in options a panel leaves out: what still fails is a key the schema
+ * doesn't have or a value it doesn't allow.
+ */
+
+import Ajv, { type ValidateFunction, type ErrorObject } from "ajv";
+import type { SchemaName } from "./pin";
+import { loadSchema } from "./spec/schemas";
+import { panelDefinitionFor } from "./panels";
+import { queryDefinitionFor } from "./query";
+
+export interface SchemaProblem {
+  /** JSON pointer into the dashboard. */
+  path: string;
+  message: string;
+}
+
+let ajv: Ajv | undefined;
+function getAjv(): Ajv {
+  ajv ??= new Ajv({ strict: false, allErrors: true, validateFormats: false });
+  return ajv;
+}
+
+const compiled = new Map<string, ValidateFunction>();
+
+function stripRequired(node: unknown): unknown {
+  if (Array.isArray(node)) return node.map(stripRequired);
+  if (node && typeof node === "object") {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(node)) {
+      if (k === "required" && Array.isArray(v)) continue;
+      out[k] = stripRequired(v);
+    }
+    return out;
+  }
+  return node;
+}
+
+/** A validator for one definition of one vendored schema (the root `$ref` when `def` is left out). */
+function validatorFor(name: SchemaName, def: string | undefined, lenient: boolean): ValidateFunction | undefined {
+  const key = `${name}#${def ?? ""}#${lenient}`;
+  const hit = compiled.get(key);
+  if (hit) return hit;
+  const schema = loadSchema(name);
+  const definitions = (schema.definitions ?? {}) as Record<string, unknown>;
+  const ref = def ? `#/definitions/${def}` : (schema.$ref as string | undefined);
+  if (!ref) return undefined;
+  if (def && !(def in definitions)) return undefined;
+  const root: Record<string, unknown> = {
+    $schema: schema.$schema,
+    $ref: ref,
+    definitions: lenient ? stripRequired(definitions) : definitions,
+  };
+  const fn = getAjv().compile(root);
+  compiled.set(key, fn);
+  return fn;
+}
+
+function problems(errors: ErrorObject[] | null | undefined, prefix: string): SchemaProblem[] {
+  const seen = new Set<string>();
+  const out: SchemaProblem[] = [];
+  for (const e of errors ?? []) {
+    // oneOf/anyOf wrappers repeat what their branches already said.
+    if (e.keyword === "oneOf" || e.keyword === "anyOf" || e.keyword === "if") continue;
+    const extra =
+      e.keyword === "additionalProperties"
+        ? ` ("${(e.params as { additionalProperty: string }).additionalProperty}")`
+        : e.keyword === "enum"
+          ? `: ${(e.params as { allowedValues: unknown[] }).allowedValues.map((v) => JSON.stringify(v)).join(", ")}`
+          : "";
+    const path = `${prefix}${e.instancePath}` || "/";
+    const message = `${e.message ?? "is invalid"}${extra}`;
+    const k = `${path} ${message}`;
+    if (seen.has(k)) continue;
+    seen.add(k);
+    out.push({ path, message });
+  }
+  return out;
+}
+
+type Json = Record<string, unknown>;
+
+function panelsOf(dashboard: Json): Array<{ panel: Json; path: string }> {
+  const out: Array<{ panel: Json; path: string }> = [];
+  const top = Array.isArray(dashboard.panels) ? (dashboard.panels as Json[]) : [];
+  top.forEach((p, i) => {
+    out.push({ panel: p, path: `/panels/${i}` });
+    if (p?.type === "row" && Array.isArray(p.panels)) {
+      (p.panels as Json[]).forEach((c, j) => out.push({ panel: c, path: `/panels/${i}/panels/${j}` }));
+    }
+  });
+  return out;
+}
+
+/** Everything in one dashboard that the pinned schemas reject. */
+export function validateDashboardSchema(dashboard: Json): SchemaProblem[] {
+  const out: SchemaProblem[] = [];
+  // The envelope and each panel are checked separately: the schema's
+  // `oneOf [Panel, RowPanel]` would otherwise report every panel error twice,
+  // once per branch.
+  const whole = validatorFor("dashboard", undefined, false)!;
+  const envelope = Array.isArray(dashboard.panels) ? { ...dashboard, panels: [] } : dashboard;
+  if (!whole(envelope)) out.push(...problems(whole.errors, ""));
+  const panelSchema = validatorFor("dashboard", "Panel", false)!;
+  const rowSchema = validatorFor("dashboard", "RowPanel", false)!;
+
+  for (const { panel, path } of panelsOf(dashboard)) {
+    if (!panel || typeof panel !== "object") {
+      out.push({ path, message: "must be object" });
+      continue;
+    }
+    if (panel.type === "row") {
+      const header = Array.isArray(panel.panels) ? { ...panel, panels: [] } : panel;
+      if (!rowSchema(header)) out.push(...problems(rowSchema.errors, path));
+      continue;
+    }
+    if (!panelSchema(panel)) out.push(...problems(panelSchema.errors, path));
+    const def = typeof panel.type === "string" ? panelDefinitionFor(panel.type) : undefined;
+    if (def?.schema) {
+      const options = validatorFor(def.schema, "Options", true);
+      if (options && panel.options !== undefined && !options(panel.options)) out.push(...problems(options.errors, `${path}/options`));
+      const custom = (panel.fieldConfig as { defaults?: { custom?: unknown } } | undefined)?.defaults?.custom;
+      const fc = validatorFor(def.schema, "FieldConfig", true);
+      if (fc && custom !== undefined && !fc(custom)) out.push(...problems(fc.errors, `${path}/fieldConfig/defaults/custom`));
+    }
+    const panelType = (panel.datasource as { type?: string } | undefined)?.type;
+    const targets = Array.isArray(panel.targets) ? (panel.targets as Json[]) : [];
+    targets.forEach((t, k) => {
+      const type = (t?.datasource as { type?: string } | undefined)?.type ?? panelType;
+      const qdef = type ? queryDefinitionFor(type) : undefined;
+      if (!qdef?.schema) return;
+      const v = validatorFor(qdef.schema, undefined, true);
+      if (v && !v(t)) out.push(...problems(v.errors, `${path}/targets/${k}`));
+    });
+  }
+  return out;
+}

package/src/schema.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, test } from "vitest";
+import { readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { GRAFANA_SCHEMA_PIN, SCHEMA_NAMES, schemaUrl } from "./pin";
+import { digestMismatches, loadSchema } from "./spec/schemas";
+import { schemaModules } from "./codegen/generate";
+import { schemaModule, tsType } from "./codegen/schema-types";
+import { DASHBOARD_SCHEMA_VERSION } from "./schema/dashboard.gen";
+
+const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+
+describe("the schema pin", () => {
+  test("names a commit and a digest for every vendored schema", () => {
+    expect(GRAFANA_SCHEMA_PIN.commit).toMatch(/^[0-9a-f]{40}$/);
+    expect(Object.keys(GRAFANA_SCHEMA_PIN.files).sort()).toEqual([...SCHEMA_NAMES].sort());
+    expect(schemaUrl("stat")).toBe(`https://raw.githubusercontent.com/grafana/grafana-foundation-sdk/${GRAFANA_SCHEMA_PIN.commit}/jsonschema/stat.jsonschema.json`);
+  });
+
+  test("every vendored schema matches its pinned digest", () => {
+    expect(digestMismatches()).toEqual([]);
+  });
+
+  test("the committed schema types are what generate writes", () => {
+    for (const [rel, source] of Object.entries(schemaModules())) {
+      expect({ rel, same: readFileSync(join(pkgDir, rel), "utf-8") === source }).toEqual({ rel, same: true });
+    }
+  });
+
+  test("the emitted schemaVersion is the pinned dashboard schema's default", () => {
+    const defs = loadSchema("dashboard").definitions as Record<string, { properties: Record<string, { default?: unknown }> }>;
+    expect(DASHBOARD_SCHEMA_VERSION).toBe(defs.Dashboard.properties.schemaVersion.default);
+  });
+});
+
+describe("schema-types", () => {
+  test("maps the draft-07 subset cog emits", () => {
+    expect(tsType({ type: "string" })).toBe("string");
+    expect(tsType({ type: "integer" })).toBe("number");
+    expect(tsType({ enum: ["a", "b"] })).toBe('"a" | "b"');
+    expect(tsType({ const: "row" })).toBe('"row"');
+    expect(tsType({ $ref: "#/definitions/dataquery" })).toBe("Dataquery");
+    expect(tsType({ anyOf: [{ type: "integer" }, { type: "null" }] })).toBe("number | null");
+    expect(tsType({ type: "array", items: { anyOf: [{ type: "string" }, { type: "number" }] } })).toBe("(string | number)[]");
+    expect(tsType({ type: "object", additionalProperties: { type: "string" } })).toBe("Record<string, string>");
+    expect(tsType({ type: "object", additionalProperties: {} })).toBe("Record<string, unknown>");
+    expect(tsType({})).toBe("unknown");
+  });
+
+  test("keeps required, marks the rest optional, and carries descriptions and deprecations", () => {
+    const { source, types } = schemaModule("text", {
+      definitions: {
+        Options: {
+          type: "object",
+          required: ["mode"],
+          properties: {
+            mode: { $ref: "#/definitions/TextMode", description: "How content renders" },
+            "odd-key": { type: "boolean", deprecated: true },
+          },
+        },
+        TextMode: { enum: ["html", "markdown"] },
+      },
+    });
+    expect(types).toEqual(["Options", "TextMode"]);
+    expect(source).toContain("export interface Options {");
+    expect(source).toContain("  mode: TextMode;");
+    expect(source).toContain('  "odd-key"?: boolean;');
+    expect(source).toContain("   * How content renders");
+    expect(source).toContain("   * @deprecated");
+    expect(source).toContain('export type TextMode = "html" | "markdown";');
+  });
+
+  test("refuses a remote $ref", () => {
+    expect(() => tsType({ $ref: "common.json#/definitions/X" })).toThrow(/local/);
+  });
+});

package/src/serializer.test.ts

@@ -0,0 +1,170 @@
+/**
+ * The grafana serializer, sectioned by the serializer checklist in the
+ * lexicon-authoring docs (testing.mdx), plus format-specific cases.
+ */
+import { describe, expect, test } from "vitest";
+import { load } from "js-yaml";
+import type { Declarable } from "@intentius/chant/declarable";
+import type { SerializerResult } from "@intentius/chant/serializer";
+import { grafanaSerializer } from "./serializer";
+import { Datasource } from "./datasource";
+import { Dashboard, DashboardProvider } from "./dashboard";
+import { StatPanel, TimeSeriesPanel } from "./panels";
+import { PromQuery } from "./query";
+import { DATASOURCES_FILE, DASHBOARD_PROVIDERS_FILE } from "./build";
+import { DASHBOARD_SCHEMA_VERSION } from "./schema/dashboard.gen";
+import { validateDashboardSchema } from "./schema-validate";
+
+function run(entries: Record<string, Declarable>): SerializerResult {
+  const out = grafanaSerializer.serialize(new Map(Object.entries(entries)));
+  if (typeof out === "string") throw new Error(`expected files, got ${JSON.stringify(out)}`);
+  return out;
+}
+
+const prometheus = new Datasource({ name: "Prometheus", type: "prometheus", url: "http://prometheus:9090" });
+const up = new PromQuery({ expr: "sum(up)" });
+const upPanel = new StatPanel({ title: "Up", datasource: prometheus, targets: [up] });
+
+describe("grafana serializer", () => {
+  // 1, 2
+  test("name and rule prefix", () => {
+    expect(grafanaSerializer.name).toBe("grafana");
+    expect(grafanaSerializer.rulePrefix).toBe("GRAF");
+  });
+
+  // 3
+  test("an empty build serializes to an empty string", () => {
+    expect(grafanaSerializer.serialize(new Map())).toBe("");
+  });
+
+  // 4
+  test("one dashboard: valid dashboard JSON and an index", () => {
+    const out = run({ overview: new Dashboard({ title: "Overview", panels: [upPanel] }) });
+    const json = JSON.parse(out.files!["dashboards/overview.json"]);
+    expect(json.title).toBe("Overview");
+    expect(json.panels).toHaveLength(1);
+    expect(validateDashboardSchema(json)).toEqual([]);
+    expect(JSON.parse(out.primary).dashboards).toEqual([{ uid: "overview", title: "Overview", file: "dashboards/overview.json" }]);
+  });
+
+  // 5
+  test("the uid defaults to the export name as a uid", () => {
+    const out = run({ checkoutServiceOverview: new Dashboard({ title: "Checkout" }) });
+    expect(Object.keys(out.files!)).toContain("dashboards/checkout-service-overview.json");
+  });
+
+  // 6
+  test("an explicit uid is kept", () => {
+    const out = run({ overview: new Dashboard({ title: "Overview", uid: "svc-ovw" }) });
+    expect(JSON.parse(out.files!["dashboards/svc-ovw.json"]).uid).toBe("svc-ovw");
+  });
+
+  // 7
+  test("several dashboards and datasources: one file each, one datasources file", () => {
+    const tempo = new Datasource({ name: "Tempo", type: "tempo", url: "http://tempo:3200" });
+    const out = run({ prometheus, tempo, a: new Dashboard({ title: "A" }), b: new Dashboard({ title: "B", folder: "Team" }) });
+    expect(Object.keys(out.files!).sort()).toEqual([
+      "dashboards/Team/b.json",
+      "dashboards/a.json",
+      DASHBOARD_PROVIDERS_FILE,
+      DATASOURCES_FILE,
+    ]);
+    const ds = load(out.files![DATASOURCES_FILE]) as { datasources: Array<{ name: string; uid: string }> };
+    expect(ds.datasources.map((d) => [d.name, d.uid])).toEqual([
+      ["Prometheus", "prometheus"],
+      ["Tempo", "tempo"],
+    ]);
+  });
+
+  // 8
+  test("defaults Grafana needs are filled in", () => {
+    const out = run({ prometheus, overview: new Dashboard({ title: "Overview", panels: [upPanel] }) });
+    const json = JSON.parse(out.files!["dashboards/overview.json"]);
+    expect(json.schemaVersion).toBe(DASHBOARD_SCHEMA_VERSION);
+    expect(json.time).toEqual({ from: "now-6h", to: "now" });
+    expect(json.templating).toEqual({ list: [] });
+    expect(json.annotations).toEqual({ list: [] });
+    expect(json.panels[0].fieldConfig).toEqual({ defaults: {}, overrides: [] });
+    const ds = load(out.files![DATASOURCES_FILE]) as { datasources: Array<Record<string, unknown>> };
+    expect(ds.datasources[0]).toMatchObject({ access: "proxy", editable: false });
+    const providers = load(out.files![DASHBOARD_PROVIDERS_FILE]) as { providers: Array<Record<string, unknown>> };
+    expect(providers.providers).toEqual([
+      {
+        name: "chant",
+        orgId: 1,
+        folder: "",
+        type: "file",
+        disableDeletion: false,
+        allowUiUpdates: false,
+        updateIntervalSeconds: 30,
+        options: { path: "/var/lib/grafana/dashboards", foldersFromFilesStructure: true },
+      },
+    ]);
+  });
+
+  // 9
+  test("explicit values override defaults", () => {
+    const provider = new DashboardProvider({ name: "team", path: "/dashboards", folder: "Team", allowUiUpdates: true });
+    const out = run({
+      provider,
+      overview: new Dashboard({ title: "Overview", time: { from: "now-1h", to: "now" }, editable: false }),
+    });
+    const json = JSON.parse(out.files!["dashboards/overview.json"]);
+    expect(json.time).toEqual({ from: "now-1h", to: "now" });
+    expect(json.editable).toBe(false);
+    const providers = load(out.files![DASHBOARD_PROVIDERS_FILE]) as { providers: Array<Record<string, unknown>> };
+    expect(providers.providers).toHaveLength(1);
+    expect(providers.providers[0]).toMatchObject({
+      name: "team",
+      folder: "Team",
+      allowUiUpdates: true,
+      options: { path: "/dashboards", foldersFromFilesStructure: false },
+    });
+  });
+
+  // 10
+  test("exported panels and queries are inlined, not emitted on their own", () => {
+    const out = run({ up, upPanel, prometheus });
+    expect(Object.keys(out.files!)).toEqual([DATASOURCES_FILE]);
+    expect(JSON.parse(out.primary).dashboards).toEqual([]);
+  });
+
+  // 11
+  test("output is the same whatever order the props were written in", () => {
+    const a = run({ d: new Dashboard({ title: "T", tags: ["x"], refresh: "1m" }) });
+    const b = run({ d: new Dashboard({ refresh: "1m", tags: ["x"], title: "T" }) });
+    expect(a.files).toEqual(b.files);
+  });
+
+  // 12
+  test("datasource references are written as { type, uid }; the index names every file", () => {
+    const loki = new Datasource({ name: "Loki", type: "loki", url: "http://loki:3100" });
+    const settings = { tracesToLogsV2: { datasourceUid: loki } };
+    const tempo = new Datasource({ name: "Tempo", type: "tempo", jsonData: settings });
+    const out = run({ loki, tempo, prometheus, overview: new Dashboard({ title: "Overview", panels: [upPanel] }) });
+    const json = JSON.parse(out.files!["dashboards/overview.json"]);
+    expect(json.panels[0].datasource).toEqual({ type: "prometheus", uid: "prometheus" });
+    expect(json.panels[0].targets[0]).toEqual({ datasource: { type: "prometheus", uid: "prometheus" }, refId: "A", expr: "sum(up)" });
+    const ds = load(out.files![DATASOURCES_FILE]) as { datasources: Array<{ name: string; jsonData?: unknown }> };
+    expect(ds.datasources.find((d) => d.name === "Tempo")?.jsonData).toEqual({ tracesToLogsV2: { datasourceUid: "loki" } });
+    expect(JSON.parse(out.primary).files).toEqual(Object.keys(out.files!).sort());
+  });
+
+  test("round trip: the emitted text parses back to the declared values", () => {
+    const panel = new TimeSeriesPanel({ title: "Rate", datasource: prometheus, targets: [up], interval: "30s" });
+    const out = run({ d: new Dashboard({ title: "Round trip", description: "desc", tags: ["a", "b"], panels: [panel] }) });
+    const json = JSON.parse(out.files!["dashboards/d.json"]);
+    expect(json).toMatchObject({ title: "Round trip", description: "desc", tags: ["a", "b"] });
+    expect(json.panels[0]).toMatchObject({ type: "timeseries", title: "Rate", interval: "30s" });
+  });
+
+  test("two dashboards with one uid keep both files, so GRAF104 can see them", () => {
+    const out = run({ a: new Dashboard({ title: "A", uid: "same" }), b: new Dashboard({ title: "B", uid: "same" }) });
+    expect(Object.keys(out.files!).filter((f) => f.startsWith("dashboards/")).sort()).toEqual(["dashboards/same-2.json", "dashboards/same.json"]);
+  });
+
+  test("entities of other lexicons are ignored", () => {
+    const foreign = { lexicon: "k8s", entityType: "K8s::Core::ConfigMap", kind: "resource", props: {} } as unknown as Declarable;
+    expect(grafanaSerializer.serialize(new Map([["cm", foreign]]))).toBe("");
+  });
+});

package/src/serializer.ts

@@ -0,0 +1,37 @@
+/**
+ * Grafana serializer.
+ *
+ * Emits Grafana's own files, as `SerializerResult.files` keyed by path
+ * relative to the output directory:
+ *
+ * - `dashboards/[<folder>/]<uid>.json`: one per dashboard, the JSON Grafana
+ *   imports as it is (UI import, the HTTP API, or file provisioning).
+ * - `provisioning/datasources/chant.yaml`: every declared datasource.
+ * - `provisioning/dashboards/chant.yaml`: the provider that loads the
+ *   dashboard files, a default one unless a `DashboardProvider` is declared.
+ *
+ * Mount `provisioning/` at `/etc/grafana/provisioning` and `dashboards/` at
+ * the provider's path (`/var/lib/grafana/dashboards` by default).
+ *
+ * The primary output is a small JSON index of what was built. Grafana's
+ * files have no metadata channel chant could use without changing what
+ * Grafana imports, so no ownership marker is stamped.
+ */
+
+import type { Declarable } from "@intentius/chant/declarable";
+import type { Serializer, SerializerResult } from "@intentius/chant/serializer";
+import type { LexiconOutput } from "@intentius/chant/lexicon-output";
+import { buildGrafana } from "./build";
+
+export const grafanaSerializer: Serializer = {
+  name: "grafana",
+  rulePrefix: "GRAF",
+
+  serialize(entities: Map<string, Declarable>, _outputs?: LexiconOutput[]): string | SerializerResult {
+    const grafana = new Map([...entities].filter(([, e]) => e?.lexicon === "grafana"));
+    if (grafana.size === 0) return "";
+    const built = buildGrafana(grafana);
+    const primary = `${JSON.stringify(built.index, null, 2)}\n`;
+    return { primary, files: built.files };
+  },
+};

package/src/skill-defs.ts

@@ -0,0 +1,31 @@
+import { createSkillsLoader } from "@intentius/chant/lexicon-plugin-helpers";
+
+/** The grafana lexicon's AI skills, read from src/skills/. */
+export const grafanaSkills = createSkillsLoader(import.meta.url, [
+  {
+    file: "chant-grafana.md",
+    name: "chant-grafana",
+    description:
+      "Declare Grafana dashboards, panels, typed Prometheus/Tempo/Loki queries and datasources as chant entities, and build dashboard JSON Grafana imports as it is",
+    triggers: [
+      { type: "context" as const, value: "grafana" },
+      { type: "context" as const, value: "grafana dashboard" },
+      { type: "file-pattern" as const, value: "*.dashboard.ts" },
+    ],
+    examples: [
+      {
+        title: "A request-rate panel on a declared Prometheus datasource",
+        output:
+          'const prometheus = new Datasource({ name: "Prometheus", type: "prometheus", url: "http://prometheus:9090" });\n' +
+          'const rate = new PromQuery({ expr: "sum(rate(http_requests_total[$__rate_interval]))" });\n' +
+          'export const overview = new Dashboard({ title: "Overview", panels: [new TimeSeriesPanel({ title: "Rate", datasource: prometheus, targets: [rate] })] });',
+      },
+    ],
+  },
+  {
+    file: "chant-grafana-provisioning.md",
+    name: "chant-grafana-provisioning",
+    description: "Load chant-built Grafana dashboards and datasources into a running Grafana through its provisioning directories, in Docker or Kubernetes",
+    triggers: [{ type: "context" as const, value: "grafana provisioning" }],
+  },
+]);