@intentius/chant-lexicon-grafana 0.97.0 → 0.99.0

package/src/panels.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, test } from "vitest";
+import * as panels from "./panels";
+import { Dashboard } from "./dashboard";
+import { renderDashboard } from "./build";
+import { validateDashboardSchema } from "./schema-validate";
+import { SCHEMA_NAMES } from "./pin";
+
+const builtins = panels.registeredPanels().filter((d) => d.builtin);
+
+describe("built-in panels", () => {
+  test("every panel type Grafana ships with a schema at the pin has a class", () => {
+    const panelSchemas = SCHEMA_NAMES.filter((n) => !["dashboard", "prometheus", "tempo", "loki", "expr"].includes(n));
+    expect(builtins.map((d) => d.schema).filter(Boolean).sort()).toEqual([...panelSchemas].sort());
+  });
+
+  test("the panels with no upstream schema are typed by hand and not validated beyond the Panel envelope", () => {
+    expect(builtins.filter((d) => !d.schema).map((d) => d.type).sort()).toEqual(["alertlist", "flamegraph", "traces"]);
+  });
+
+  test("the node graph keeps Grafana's camelCase id; a plugin chant does not ship may not", () => {
+    expect(panels.NodeGraphPanel.definition.type).toBe("nodeGraph");
+    expect(() => panels.definePanel()({ type: "myGraph", className: "MyGraph", defaultSize: { w: 1, h: 1 } })).toThrow(/not a panel plugin id/);
+  });
+
+  test.each(builtins.map((d) => [d.className, d] as const))("%s renders a dashboard GRAF107 accepts", (_name, def) => {
+    const Cls = (panels as unknown as Record<string, panels.PanelClass>)[def.className];
+    const json = renderDashboard(new Dashboard({ title: def.className, panels: [new Cls({ title: "p" })] }));
+    expect(json.panels![0]).toMatchObject({ type: def.type, gridPos: { w: def.defaultSize.w, h: def.defaultSize.h } });
+    expect(validateDashboardSchema(json as unknown as Record<string, unknown>)).toEqual([]);
+  });
+
+  test("typed options reach the JSON, and a value the schema rejects is a GRAF107 error", () => {
+    const pie = new panels.PieChartPanel({ options: { pieType: "donut", sort: "desc", displayLabels: ["percent"] } });
+    const ok = renderDashboard(new Dashboard({ title: "Pie", panels: [pie] }));
+    expect((ok.panels![0] as { options?: unknown }).options).toEqual({ pieType: "donut", sort: "desc", displayLabels: ["percent"] });
+    expect(validateDashboardSchema(ok as unknown as Record<string, unknown>)).toEqual([]);
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const bad = new panels.BarGaugePanel({ options: { displayMode: "sparkle" as any } });
+    const problems = validateDashboardSchema(renderDashboard(new Dashboard({ title: "Bad", panels: [bad] })) as unknown as Record<string, unknown>);
+    expect(problems).toEqual([expect.objectContaining({ path: "/panels/0/options/displayMode", severity: "error" })]);
+  });
+
+  test("the hand-typed alert list options type what Grafana writes", () => {
+    const list = new panels.AlertListPanel({ options: { viewMode: "stat", sortOrder: 3, stateFilter: { firing: true, error: true }, folder: null } });
+    expect(renderDashboard(new Dashboard({ title: "Alerts", panels: [list] })).panels![0]).toMatchObject({
+      type: "alertlist",
+      options: { viewMode: "stat", sortOrder: 3, stateFilter: { firing: true, error: true }, folder: null },
+    });
+  });
+});

package/src/panels.ts

@@ -11,8 +11,10 @@
  *
  * `gridPos` is optional. A panel without `x` and `y` is placed by the
  * dashboard: left to right in declaration order, wrapping at Grafana's
- * 24-column width, below the previous row of panels. A panel with both is
- * placed exactly there, and GRAF105 reports overlaps.
+ * 24-column width, below the previous row of panels, and around any cells
+ * already taken. A panel with both is placed exactly there and reserves its
+ * cells first; GRAF105 reports overlaps between explicit panels. A panel
+ * with only `x` or only `y` keeps that column or line.
  */
 
 import { createProperty } from "@intentius/chant/runtime";
@@ -23,7 +25,6 @@ import type { VariableEntity } from "./variables";
 import type { SchemaName } from "./pin";
 import type {
   DashboardLink,
-  DataTransformerConfig,
   FieldConfig,
   FieldConfigSource,
   GridPos,
@@ -35,6 +36,19 @@ import type * as table from "./schema/table.gen";
 import type * as logs from "./schema/logs.gen";
 import type * as heatmap from "./schema/heatmap.gen";
 import type * as text from "./schema/text.gen";
+import type * as barchart from "./schema/barchart.gen";
+import type * as bargauge from "./schema/bargauge.gen";
+import type * as piechart from "./schema/piechart.gen";
+import type * as statetimeline from "./schema/statetimeline.gen";
+import type * as statushistory from "./schema/statushistory.gen";
+import type * as histogram from "./schema/histogram.gen";
+import type * as nodegraph from "./schema/nodegraph.gen";
+import type * as xychart from "./schema/xychart.gen";
+import type * as trend from "./schema/trend.gen";
+import type * as canvas from "./schema/canvas.gen";
+import type * as geomap from "./schema/geomap.gen";
+import type { AlertListOptions, FlameGraphOptions } from "./panel-options";
+import type { Transformation } from "./transformations";
 
 /** `fieldConfig` with `defaults.custom` typed for the panel. */
 export interface PanelFieldConfig<C> {
@@ -59,7 +73,8 @@ export interface PanelProps<O = Record<string, unknown>, C = Record<string, unkn
   /** The panel plugin's own options, typed from its schema. */
   options?: DeepPartial<O>;
   fieldConfig?: PanelFieldConfig<C>;
-  transformations?: DataTransformerConfig[];
+  /** Typed per transformer: `{ id: "organize", options: { ... } }`, `transformation(id, options)`, or `customTransformation()` for an id or option the types don't know. */
+  transformations?: Transformation[];
   links?: PanelLink[];
   /** Repeat the panel once per value of this variable. */
   repeat?: VariableEntity | string;
@@ -118,9 +133,11 @@ export function panelDefinitionFor(type: string): PanelDefinition | undefined {
 }
 
 const PLUGIN_ID = /^[a-z0-9][a-z0-9-_]*$/;
+/** Core panel ids predate the lowercase rule plugin ids follow: the node graph is `nodeGraph`. */
+const CORE_PLUGIN_ID = /^[A-Za-z0-9][A-Za-z0-9-_]*$/;
 
 function makePanelClass<T extends string, O, C>(def: PanelDefinition<T>): PanelClass<T, O, C> {
-  if (!PLUGIN_ID.test(def.type)) throw new Error(`grafana: "${def.type}" is not a panel plugin id`);
+  if (!(def.builtin ? CORE_PLUGIN_ID : PLUGIN_ID).test(def.type)) throw new Error(`grafana: "${def.type}" is not a panel plugin id`);
   if (def.type === "row") throw new Error('grafana: "row" is not a panel; use Row');
   const existing = registry().get(def.type);
   if (existing?.builtin && !def.builtin) {
@@ -145,12 +162,12 @@ function makePanelClass<T extends string, O, C>(def: PanelDefinition<T>): PanelC
  *
  * @example
  * ```ts
- * interface PieOptions { pieType?: "pie" | "donut"; legend?: { showLegend?: boolean } }
+ * interface ClockOptions { mode?: "time" | "countdown"; clockType?: "24 hour" | "12 hour" }
  *
- * export const PieChartPanel = definePanel<PieOptions>()({
- *   type: "piechart",
- *   className: "PieChartPanel",
- *   defaultSize: { w: 8, h: 8 },
+ * export const ClockPanel = definePanel<ClockOptions>()({
+ *   type: "grafana-clock-panel",
+ *   className: "ClockPanel",
+ *   defaultSize: { w: 6, h: 4 },
  * });
  * ```
  */
@@ -243,6 +260,121 @@ export const TextPanel = makePanelClass<"text", text.Options, Record<string, unk
   builtin: true,
 });
 
+export const BarChartPanel = makePanelClass<"barchart", barchart.Options, barchart.FieldConfig>({
+  type: "barchart",
+  className: "BarChartPanel",
+  description: "Bar chart: categorical values as bars, grouped or stacked",
+  defaultSize: { w: 12, h: 8 },
+  schema: "barchart",
+  builtin: true,
+});
+
+export const BarGaugePanel = makePanelClass<"bargauge", bargauge.Options, Record<string, unknown>>({
+  type: "bargauge",
+  className: "BarGaugePanel",
+  description: "Bar gauge: one bar per series, filled against min, max and thresholds",
+  defaultSize: { w: 12, h: 8 },
+  schema: "bargauge",
+  builtin: true,
+});
+
+export const PieChartPanel = makePanelClass<"piechart", piechart.Options, piechart.FieldConfig>({
+  type: "piechart",
+  className: "PieChartPanel",
+  description: "Pie chart: each series' share of the total, as a pie or donut",
+  defaultSize: { w: 8, h: 8 },
+  schema: "piechart",
+  builtin: true,
+});
+
+export const StateTimelinePanel = makePanelClass<"state-timeline", statetimeline.Options, statetimeline.FieldConfig>({
+  type: "state-timeline",
+  className: "StateTimelinePanel",
+  description: "State timeline: state changes over time, one lane per series",
+  defaultSize: { w: 24, h: 8 },
+  schema: "statetimeline",
+  builtin: true,
+});
+
+export const StatusHistoryPanel = makePanelClass<"status-history", statushistory.Options, statushistory.FieldConfig>({
+  type: "status-history",
+  className: "StatusHistoryPanel",
+  description: "Status history: periodic states over time as a grid of cells",
+  defaultSize: { w: 24, h: 8 },
+  schema: "statushistory",
+  builtin: true,
+});
+
+export const HistogramPanel = makePanelClass<"histogram", histogram.Options, histogram.FieldConfig>({
+  type: "histogram",
+  className: "HistogramPanel",
+  description: "Histogram: the distribution of values, bucketed, over the whole time range",
+  defaultSize: { w: 12, h: 8 },
+  schema: "histogram",
+  builtin: true,
+});
+
+export const NodeGraphPanel = makePanelClass<"nodeGraph", nodegraph.Options, Record<string, unknown>>({
+  type: "nodeGraph",
+  className: "NodeGraphPanel",
+  description: "Node graph: a directed graph of nodes and edges, e.g. a service map",
+  defaultSize: { w: 24, h: 12 },
+  schema: "nodegraph",
+  builtin: true,
+});
+
+export const XYChartPanel = makePanelClass<"xychart", xychart.Options, xychart.FieldConfig>({
+  type: "xychart",
+  className: "XYChartPanel",
+  description: "XY chart: one field plotted against another, as points or lines",
+  defaultSize: { w: 12, h: 8 },
+  schema: "xychart",
+  builtin: true,
+});
+
+export const TrendPanel = makePanelClass<"trend", trend.Options, trend.FieldConfig>({
+  type: "trend",
+  className: "TrendPanel",
+  description: "Trend: values against a numeric x field that is not time",
+  defaultSize: { w: 12, h: 8 },
+  schema: "trend",
+  builtin: true,
+});
+
+export const CanvasPanel = makePanelClass<"canvas", canvas.Options, Record<string, unknown>>({
+  type: "canvas",
+  className: "CanvasPanel",
+  description: "Canvas: freely placed elements, text, icons and metrics bound to data",
+  defaultSize: { w: 12, h: 10 },
+  schema: "canvas",
+  builtin: true,
+});
+
+export const GeomapPanel = makePanelClass<"geomap", geomap.Options, Record<string, unknown>>({
+  type: "geomap",
+  className: "GeomapPanel",
+  description: "Geomap: data on a world map, as markers, heatmaps or routes",
+  defaultSize: { w: 12, h: 10 },
+  schema: "geomap",
+  builtin: true,
+});
+
+export const FlameGraphPanel = makePanelClass<"flamegraph", FlameGraphOptions, Record<string, unknown>>({
+  type: "flamegraph",
+  className: "FlameGraphPanel",
+  description: "Flame graph: profiling data, e.g. from Pyroscope, as a flame graph and table",
+  defaultSize: { w: 24, h: 12 },
+  builtin: true,
+});
+
+export const AlertListPanel = makePanelClass<"alertlist", AlertListOptions, Record<string, unknown>>({
+  type: "alertlist",
+  className: "AlertListPanel",
+  description: "Alert list: alert rules and their current state, no queries",
+  defaultSize: { w: 8, h: 10 },
+  builtin: true,
+});
+
 // ── Rows ────────────────────────────────────────────────────────
 
 export interface RowProps {
@@ -256,6 +388,12 @@ export interface RowProps {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   datasource?: DatasourceInput<any>;
   id?: number;
+  /**
+   * The grid line the row header sits on. Without it, the row goes on the
+   * first free line below everything declared before it. A row header is
+   * always full width and one line high, so `y` is all it takes.
+   */
+  gridPos?: { y: number };
 }
 
 export interface RowEntity extends Declarable {

package/src/pin.ts

@@ -5,12 +5,19 @@
  * kinds. `grafana/grafana-foundation-sdk` runs them through cog and
  * publishes, beside its builder libraries, one JSON Schema per kind under
  * `jsonschema/`. This lexicon vendors the files it uses into `src/spec/schemas/`
- * (exact bytes, at the commit below) and generates `src/schema/*.gen.ts`
- * from them. Nothing is fetched at build or test time.
+ * (exact bytes, at the commit below), applies the correction overlay in
+ * `src/spec/overlay/` (see `src/spec/overlay.ts`), and generates
+ * `src/schema/*.gen.ts` from the result. Nothing is fetched at build or test
+ * time.
+ *
+ * The types track Grafana 12.4 and 13.x: v0.0.20 is labelled with the
+ * v11.6.x kind registry, but its dashboard schema largely matches those
+ * releases, and the overlay covers the rest.
  *
  * Bumping the pin: change `ref` and `commit`, run `just fetch-schemas`
  * (downloads and prints the new digests), paste the digests here, run
- * `npm run generate`, and review the diff of `src/schema/`.
+ * `npm run generate` (it refuses overlay patches the new schemas already
+ * carry; delete those), and review the diff of `src/schema/`.
  */
 
 export interface GrafanaSchemaPin {
@@ -20,10 +27,13 @@ export interface GrafanaSchemaPin {
   ref: string;
   /** The exact commit the vendored files were taken from. */
   commit: string;
-  /** The Grafana kind registry version cog generated the schemas from. */
+  /**
+   * The kind registry label the SDK publishes the schemas under. It lags the
+   * content: the v0.0.20 schemas are labelled v11.6.x and cover 12.4 and 13.x.
+   */
   kindRegistry: string;
   /** sha256 of each vendored file, keyed by schema name (`src/spec/schemas/<name>.jsonschema.json`). */
-  files: Readonly<Record<SchemaName, string>>;
+  files: Readonly<Record<VendoredSchemaName, string>>;
 }
 
 export const SCHEMA_NAMES = [
@@ -35,13 +45,41 @@ export const SCHEMA_NAMES = [
   "logs",
   "heatmap",
   "text",
+  "barchart",
+  "bargauge",
+  "piechart",
+  "statetimeline",
+  "statushistory",
+  "histogram",
+  "nodegraph",
+  "xychart",
+  "trend",
+  "canvas",
+  "geomap",
   "prometheus",
   "tempo",
   "loki",
+  "expr",
 ] as const;
 
 export type SchemaName = (typeof SCHEMA_NAMES)[number];
 
+/**
+ * Schemas vendored from the same commit for reading, not for types: no
+ * `.gen.ts` is generated from them and GRAF107 does not use them, since chant
+ * builds classic dashboards. `dashboardv2` is the v2 dashboard kind the
+ * importer reads (#2947); `src/import/v2.test.ts` checks the importer knows
+ * every key it defines.
+ */
+export const IMPORT_ONLY_SCHEMA_NAMES = ["dashboardv2"] as const;
+
+export type ImportOnlySchemaName = (typeof IMPORT_ONLY_SCHEMA_NAMES)[number];
+
+/** Every schema file under `src/spec/schemas/`. */
+export type VendoredSchemaName = SchemaName | ImportOnlySchemaName;
+
+export const VENDORED_SCHEMA_NAMES: readonly VendoredSchemaName[] = [...SCHEMA_NAMES, ...IMPORT_ONLY_SCHEMA_NAMES];
+
 export const GRAFANA_SCHEMA_PIN: GrafanaSchemaPin = Object.freeze({
   source: "github.com/grafana/grafana-foundation-sdk/jsonschema",
   ref: "v0.0.20",
@@ -56,13 +94,26 @@ export const GRAFANA_SCHEMA_PIN: GrafanaSchemaPin = Object.freeze({
     logs: "0254600ef9720bd2c906628304a7c362c0182b4bff2fd7d91352d95a269b2dda",
     heatmap: "1e1905eef14ada48c121374ecad41412380b317e8183771d99a7504753d5005c",
     text: "db6d2e3e2c576d1c78ac2e08930f60dbc22bb7ee21abd0cd9204be49f0dbce09",
+    barchart: "36f16c10ac3529f88435b81af1d2e352bc915d228a0fb0418d4e46cc2615f6cb",
+    bargauge: "dbd22a7b71c4133b880ad39daeaf33c5bf0509fe0d5dc7a882fe3449207b636f",
+    piechart: "3edcd85eb8333db755562fc360e392795617582c8d03d11f5918247a4b0ceea9",
+    statetimeline: "4df9f488db587b074de51e2b10d6361e3dd390f110aee105029f334b863bd365",
+    statushistory: "3149edd7e3c9567913bb123ee764b118c816b9865ab7ec1f19275335b670f4b3",
+    histogram: "ef30d7b439b5ece72783be27575b736745aa3eedade37919fcf7560427eb09ac",
+    nodegraph: "76595130348310202d87c0efd1e248d60f391cf4cf39c0d3c8d30a251c1f9461",
+    xychart: "071b4866d0d292c772adb5946a6cae94cc2486b4a0acabb6247090b5f7a83f9f",
+    trend: "599a241e922217be840a65fbf731f7883a3304fd2b6074af01650d325ec0e629",
+    canvas: "53e5069cfeef461913cec759c120bc31167b7532be2b69d3c45ce7e4877290d7",
+    geomap: "8c8716e9bdbb6b0465b2e91ad1a1100d96a02b7f1be606bd90a6676d94897179",
     prometheus: "726fc97eeb1e37791dbbf988c3cf40de17bb8e623926e6979c4a3f947cb1af87",
     tempo: "21aec4c333c9b8e5e9228e85a6225c76161975abb54002e6f12e919e3b4e54ae",
     loki: "03b81d6b952e3d31785c4b52637e2b7b1c170cc2ea8ec7ec671c21599508e31b",
+    expr: "b1f1c1e4f6bf00f0fb4cb32b5bcc1b0e91fad9b7ad9354ecb791322bd97a5564",
+    dashboardv2: "a2cfb8b731ff9f48c41f5aa06ade134cf0d93ab9f6f0567a34a4bc39a9fd984e",
   }),
 });
 
 /** The raw URL of one schema file at the pinned commit. */
-export function schemaUrl(name: SchemaName, pin: GrafanaSchemaPin = GRAFANA_SCHEMA_PIN): string {
+export function schemaUrl(name: VendoredSchemaName, pin: GrafanaSchemaPin = GRAFANA_SCHEMA_PIN): string {
   return `https://raw.githubusercontent.com/grafana/grafana-foundation-sdk/${pin.commit}/jsonschema/${name}.jsonschema.json`;
 }

package/src/plugin.test.ts

@@ -16,7 +16,7 @@ describe("grafana plugin", () => {
 
   it("ships lint rules and post-synth checks, all under the GRAF prefix", () => {
     const ids = [...grafanaPlugin.lintRules!().map((r) => r.id), ...grafanaPlugin.postSynthChecks!().map((c) => c.id)];
-    expect(ids).toEqual(["GRAF001", "GRAF002", "GRAF101", "GRAF102", "GRAF103", "GRAF104", "GRAF105", "GRAF106", "GRAF107"]);
+    expect(ids).toEqual(["GRAF001", "GRAF002", "GRAF101", "GRAF102", "GRAF103", "GRAF104", "GRAF105", "GRAF106", "GRAF107", "GRAF108", "GRAF109", "GRAF111", "GRAF112", "GRAF113", "GRAF114", "GRAF115"]);
   });
 
   it("catalogues every rule and check for chant audit, and nothing else", () => {
@@ -29,13 +29,16 @@ describe("grafana plugin", () => {
     expect(grafanaPlugin.detectTemplate!({ panels: [], schemaVersion: 41, title: "x" })).toBe(true);
     expect(grafanaPlugin.detectTemplate!({ apiVersion: 1, datasources: [] })).toBe(true);
     expect(grafanaPlugin.detectTemplate!({ apiVersion: 1, providers: [] })).toBe(true);
+    expect(grafanaPlugin.detectTemplate!({ apiVersion: 1, groups: [{ name: "g", folder: "F", rules: [] }] })).toBe(true);
+    expect(grafanaPlugin.detectTemplate!({ apiVersion: 1, contactPoints: [] })).toBe(true);
+    expect(grafanaPlugin.detectTemplate!({ groups: [{ name: "g", rules: [{ alert: "A", expr: "up == 0" }] }] })).toBe(false);
     expect(grafanaPlugin.detectTemplate!({ apiVersion: "v1", kind: "ConfigMap" })).toBe(false);
     expect(grafanaPlugin.detectTemplate!({ receivers: {}, service: { pipelines: {} } })).toBe(false);
   });
 
   it("loads its skills with content", () => {
     const skills = grafanaPlugin.skills!();
-    expect(skills.map((s) => s.name)).toEqual(["chant-grafana", "chant-grafana-provisioning"]);
+    expect(skills.map((s) => s.name)).toEqual(["chant-grafana", "chant-grafana-provisioning", "chant-grafana-alerting"]);
     for (const s of skills) expect(s.content.length).toBeGreaterThan(200);
   });
 

package/src/plugin.ts

@@ -1,4 +1,5 @@
 import type { LexiconPlugin } from "@intentius/chant/lexicon";
+import type { OwnershipChannel } from "@intentius/chant/ownership";
 import type { CompletionContext, HoverContext } from "@intentius/chant/lsp/types";
 import type { McpResourceContribution } from "@intentius/chant/mcp/types";
 import { createDiffTool } from "@intentius/chant/lexicon-plugin-helpers";
@@ -9,10 +10,16 @@ import { grafanaAuditCatalog } from "./lint/audit-catalog";
 import { completions } from "./lsp/completions";
 import { hover } from "./lsp/hover";
 import { detectTemplate } from "./detect";
+import { GrafanaParser } from "./import/parser";
+import { GrafanaGenerator } from "./import/generator";
+import { dashboardImporter } from "./import/embedded";
 import { grafanaSkills } from "./skill-defs";
 import { BUILTIN_CATALOG } from "./catalog";
 import { GRAFANA_SCHEMA_PIN } from "./pin";
 import { compositeCatalog } from "./composites/catalog";
+import { grafanaConfigSchema } from "./config";
+import { grafanaDeepNormalizationHooks } from "./deep-observe-hooks";
+import { GRAFANA_OWNERSHIP_KEYS } from "./ownership";
 
 const catalogResource: McpResourceContribution = {
   uri: "grafana:resource-catalog",
@@ -24,6 +31,23 @@ const catalogResource: McpResourceContribution = {
   },
 };
 
+/**
+ * Where chant's marker can be read (#2946, see ./ownership.ts).
+ *
+ * A dashboard read over `/apis/dashboard.grafana.app` resolves `owned` or
+ * `foreign` on all three paths: from chant's managed-by label (stack and env
+ * included) when it was written through the API, or from the manager
+ * annotation Grafana writes on a dashboard one of the project's providers
+ * loaded. What resolves nothing, and says `unknown`, is kind- and
+ * server-shaped rather than path-shaped: datasources (their API has no
+ * labels) and dashboards on Grafana 11 (read over `/api/dashboards/uid`).
+ * An `owned: true` read withholds those as `filtered`.
+ */
+const ownershipChannel: OwnershipChannel = {
+  keys: GRAFANA_OWNERSHIP_KEYS,
+  reads: ["describeResources", "observeResourcesDeep", "exportResources"],
+};
+
 /**
  * Grafana lexicon plugin.
  *
@@ -36,6 +60,8 @@ const catalogResource: McpResourceContribution = {
 export const grafanaPlugin: LexiconPlugin = {
   name: "grafana",
   serializer: grafanaSerializer,
+  configSchema: grafanaConfigSchema,
+  ownershipChannel,
 
   // ── Required lifecycle methods ────────────────────────────────
 
@@ -75,6 +101,12 @@ export const grafanaPlugin: LexiconPlugin = {
     return rules;
   },
 
+  // Panels, rows, queries and variables live inside a dashboard, so core
+  // lint does not count them as resources (chant #2957).
+  propertyClassNames() {
+    return BUILTIN_CATALOG.filter((e) => e.entityKind === "property").map((e) => e.className);
+  },
+
   postSynthChecks() {
     return postSynthChecks;
   },
@@ -101,6 +133,18 @@ export const grafanaPlugin: LexiconPlugin = {
     return detectTemplate(data);
   },
 
+  templateParser() {
+    return new GrafanaParser();
+  },
+
+  templateGenerator() {
+    return new GrafanaGenerator();
+  },
+
+  embeddedImporters() {
+    return [dashboardImporter];
+  },
+
   completionProvider(ctx: CompletionContext) {
     return completions(ctx);
   },
@@ -109,6 +153,28 @@ export const grafanaPlugin: LexiconPlugin = {
     return hover(ctx);
   },
 
+  // ── Live observation and export (#2946) ──────────────────────
+  // Behind dynamic imports, so `chant build` never loads a transport. The
+  // hooks are static: core normalizes the declared tree with them whether or
+  // not a live read happens.
+
+  async describeResources(options) {
+    const { describeResources } = await import("./describe-resources");
+    return describeResources(options);
+  },
+
+  async observeResourcesDeep(options) {
+    const { observeResourcesDeepGrafana } = await import("./deep-observe");
+    return observeResourcesDeepGrafana(options);
+  },
+
+  deepNormalizationHooks: grafanaDeepNormalizationHooks,
+
+  async exportResources(options) {
+    const { exportResources } = await import("./export-resources");
+    return exportResources(options);
+  },
+
   async docs(options?: { verbose?: boolean }) {
     const { generateDocs } = await import("./codegen/docs");
     return generateDocs(options);

package/src/promql-check.test.ts

@@ -0,0 +1,108 @@
+/**
+ * GRAF108's pieces: template-variable substitution, the PromQL inside a
+ * Prometheus query variable, and which queries of a dashboard get parsed.
+ * The check itself, over built and hand-written dashboards, is in
+ * lint/post-synth/post-synth.test.ts.
+ */
+import { describe, expect, test } from "vitest";
+import { checkGrafanaPromql, prometheusQueries, substituteTemplateVariables, variablePromql } from "./promql-check";
+import { knownDatasources } from "./datasource-refs";
+
+describe("substituteTemplateVariables", () => {
+  test.each([
+    ['sum(rate(x{a=~"$a"}[$__rate_interval]))', 'sum(rate(x{a=~"$a"}[5m]))'],
+    ["rate(x[$__interval:$__interval])", "rate(x[5m:5m])"],
+    ["rate(x[${window}]) offset $shift", "rate(x[5m]) offset 5m"],
+    ["rate(x[${minutes}m])", "rate(x[1m])"],
+    ['$metric{job="a"} / $__range_s', 'grafana_var{job="a"} / 1'],
+    ["sum by ($group) (x) * $__interval_ms", "sum by (grafana_var) (x) * 1"],
+    ["x @ ${__to:date:seconds}", "x @ 1"],
+    ["rate([[metric]][[[w]]])", "rate(grafana_var[5m])"],
+    ["topk(${n:raw}, x)", "topk(grafana_var, x)"],
+    ["x{a='$a', b=`$b`}", "x{a='$a', b=`$b`}"],
+    ['x{a="\\"$a"}[$__range]', 'x{a="\\"$a"}[5m]'],
+  ])("%s", (query, text) => {
+    expect(substituteTemplateVariables(query).text).toBe(text);
+  });
+
+  test("maps offsets in the substituted text back to the query", () => {
+    const s = substituteTemplateVariables("rate(x[$__rate_interval]) +");
+    expect(s.text).toBe("rate(x[5m]) +");
+    expect(s.originalOffset(7)).toBe(7);
+    expect(s.originalOffset(8)).toBe(7);
+    expect(s.originalOffset(11)).toBe(25);
+  });
+});
+
+describe("checkGrafanaPromql", () => {
+  test("passes the queries Grafana's own dashboards use", () => {
+    for (const q of [
+      'histogram_quantile(0.99, sum by (le) (rate(http_request_duration_seconds_bucket{route=~"$route"}[$__rate_interval])))',
+      'sum by (route) (rate(http_requests_total{job=~"$job", env=~"$env"}[$window]))',
+      "sum(increase(x[$__range])) / ($__range_s)",
+      'up{instance=~"[[instance]]"}',
+    ]) {
+      expect({ q, r: checkGrafanaPromql(q) }).toEqual({ q, r: { ok: true } });
+    }
+  });
+
+  test("reports an unbalanced expression against the original text", () => {
+    const r = checkGrafanaPromql('sum(x{cluster="$cluster"}');
+    expect(r).toEqual({ ok: false, message: expect.stringContaining('ends early (after "sum(x{cluster="$cluster"}")') });
+  });
+
+  test("reports the offset in the query as written, not as substituted", () => {
+    const r = checkGrafanaPromql("rate(x[$__rate_interval]) by");
+    expect(r.ok).toBe(false);
+    if (!r.ok) expect(r.message).toMatch(/offset 2\d: "rate\(x\[\$__rate_interval\]\) ?" >>> /);
+  });
+});
+
+describe("variablePromql", () => {
+  test.each([
+    ["label_names()", []],
+    ['label_names(up{job="a"})', ['up{job="a"}']],
+    ["label_values(job)", []],
+    ['label_values(up{env="$env"}, job)', ['up{env="$env"}']],
+    ["metrics(^http_.*)", []],
+    ["query_result(topk(5, sum by (job) (up)))", ["topk(5, sum by (job) (up))"]],
+    ['up{job="a"}', ['up{job="a"}']],
+    ["  ", []],
+  ])("%s", (query, promql) => {
+    expect(variablePromql(query)).toEqual(promql);
+  });
+});
+
+describe("prometheusQueries", () => {
+  const known = knownDatasources([
+    { name: "Prometheus", type: "prometheus", uid: "prom" },
+    { name: "Loki", type: "loki", uid: "loki" },
+  ]);
+  const dashboard = {
+    templating: {
+      list: [
+        { type: "datasource", name: "ds", query: "prometheus" },
+        { type: "query", name: "job", datasource: { type: "prometheus", uid: "prom" }, query: { query: "label_values(up, job)", refId: "V" } },
+        { type: "query", name: "stream", datasource: { type: "loki", uid: "loki" }, query: "label_values(app)" },
+      ],
+    },
+    panels: [
+      { id: 1, title: "a", type: "stat", datasource: { type: "prometheus", uid: "prom" }, targets: [{ refId: "A", expr: "up" }, { refId: "B", expr: "" }] },
+      { id: 2, title: "b", type: "logs", datasource: { type: "loki", uid: "loki" }, targets: [{ refId: "A", expr: '{app="x"} |= "error"' }] },
+      { id: 3, title: "c", type: "stat", datasource: { type: "prometheus", uid: "${ds}" }, targets: [{ refId: "A", expr: "sum(up)" }] },
+      { id: 4, title: "d", type: "stat", targets: [{ refId: "A", expr: "no datasource" }] },
+      { id: 5, title: "e", type: "stat", datasource: { type: "datasource", uid: "-- Mixed --" }, targets: [{ refId: "A", expr: "x", datasource: { type: "loki", uid: "loki" } }, { refId: "B", expr: "y", datasource: { type: "prometheus", uid: "prom" } }] },
+    ],
+    __elements: { lib: { name: "lib", kind: 1, model: { type: "stat", datasource: { type: "prometheus", uid: "prom" }, targets: [{ refId: "A", expr: "rate(x[5m])" }] } } },
+  };
+
+  test("takes only the queries that reach a Prometheus, including library panels", () => {
+    expect(prometheusQueries(dashboard, known)).toEqual([
+      { where: 'panel "a" (id 1) query A', expr: "up" },
+      { where: 'panel "c" (id 3) query A', expr: "sum(up)" },
+      { where: 'panel "e" (id 5) query B', expr: "y" },
+      { where: 'variable "job" query', expr: "up" },
+      { where: 'library panel "lib" query A', expr: "rate(x[5m])" },
+    ]);
+  });
+});