@intentius/chant-lexicon-grafana 0.98.0 → 0.100.0

package/src/panel-options.ts

@@ -0,0 +1,66 @@
+/**
+ * Hand-written option types for the built-in panels that have no schema.
+ *
+ * The alert list and flame graph panels define their options in TypeScript
+ * inside Grafana's frontend, with no CUE kind, so foundation-sdk publishes
+ * no JSON Schema for them and `npm run generate` has nothing to read. The
+ * types here follow Grafana's source at v13.2.2, cited per type. GRAF107
+ * checks these panels' envelope (the dashboard schema's `Panel`) but not
+ * their `options`; the traces panel is in the same position and keeps
+ * untyped options.
+ */
+
+import type { ThresholdsConfig, ValueMapping } from "./schema/dashboard.gen";
+
+/**
+ * How the alert list orders rules: `SortOrder` in
+ * public/app/plugins/panel/alertlist/types.ts:4-10 (a numeric enum starting at 1).
+ * 1 alphabetical ascending, 2 descending, 3 by importance, 4 time ascending, 5 time descending.
+ */
+export type AlertListSortOrder = 1 | 2 | 3 | 4 | 5;
+
+/** Which rule states the alert list shows: `StateFilter`, public/app/plugins/panel/alertlist/types.ts:22-30. */
+export interface AlertListStateFilter {
+  firing: boolean;
+  pending: boolean;
+  /** Kept for dashboards saved before 9.x. */
+  inactive: boolean;
+  recovering: boolean;
+  noData: boolean;
+  normal: boolean;
+  error: boolean;
+}
+
+/**
+ * The alert list panel's options: `UnifiedAlertListOptions`,
+ * public/app/plugins/panel/alertlist/types.ts:32-49 at v13.2.2. Defaults are in
+ * public/app/plugins/panel/alertlist/module.tsx.
+ */
+export interface AlertListOptions {
+  maxItems: number;
+  sortOrder: AlertListSortOrder;
+  /** Only rules from the dashboard the panel is on. */
+  dashboardAlerts: boolean;
+  groupMode: "default" | "custom";
+  groupBy: string[];
+  alertName: string;
+  showInstances: boolean;
+  /** Only rules in this folder; null for any. */
+  folder: { uid: string; title: string } | null;
+  stateFilter: AlertListStateFilter;
+  alertInstanceLabelFilter: string;
+  /** The rule source's datasource name, or null for all. */
+  datasource: string | null;
+  viewMode: "list" | "stat";
+  showInactiveAlerts: boolean;
+  /** `BigValueColorMode`, packages/grafana-ui/src/components/BigValue/BigValueTypes.ts:8-13. */
+  statColorMode: "background" | "background_solid" | "none" | "value";
+  statThresholds: ThresholdsConfig;
+  statValueMappings: ValueMapping[];
+}
+
+/** The flame graph panel's options: `Options`, public/app/plugins/panel/flamegraph/types.ts:1-3 at v13.2.2. */
+export interface FlameGraphOptions {
+  /** Hide the top table and show only the flame graph. */
+  showFlameGraphOnly: boolean;
+}

package/src/panels.test.ts

@@ -0,0 +1,53 @@
+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";
+import { registeredQueries } from "./query";
+
+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 querySchemas = new Set<string>(registeredQueries().flatMap((d) => (d.schema ? [d.schema] : [])));
+    const panelSchemas = SCHEMA_NAMES.filter((n) => n !== "dashboard" && n !== "expr" && !querySchemas.has(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,47 @@ export const SCHEMA_NAMES = [
   "logs",
   "heatmap",
   "text",
+  "barchart",
+  "bargauge",
+  "piechart",
+  "statetimeline",
+  "statushistory",
+  "histogram",
+  "nodegraph",
+  "xychart",
+  "trend",
+  "canvas",
+  "geomap",
   "prometheus",
   "tempo",
   "loki",
+  "elasticsearch",
+  "cloudwatch",
+  "azuremonitor",
+  "googlecloudmonitoring",
+  "bigquery",
+  "grafanapyroscope",
+  "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 +100,32 @@ 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",
+    elasticsearch: "126b0e04116877f468df7474ad6f75167cf9c54feb125534211fbe1915e6421e",
+    cloudwatch: "06d50341c82420865f3f58bfd3e3081cd90fb625f1d275bb7ba0230033f9db3f",
+    azuremonitor: "fe0f2fc01ff626dec7ce17a0e3dbb2e76f51f20539c73bbded46bbc4c2d3e262",
+    googlecloudmonitoring: "e1f2e2086d4216f22aca84def440b6a31a76e074727aa2ea3d2d10671e68834b",
+    bigquery: "939a0a6aee2c98fd8f690659e17060ff2b5bad1b22437e3449741ce0acc5abe4",
+    grafanapyroscope: "297db04efc4f9501ffa729acd9e02e484998bc4d823c7da362e401faceed64a2",
+    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", "GRAF110", "GRAF111", "GRAF112", "GRAF113", "GRAF114", "GRAF115"]);
   });
 
   it("catalogues every rule and check for chant audit, and nothing else", () => {
@@ -29,16 +29,26 @@ 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", "chant-grafana-operations"]);
     for (const s of skills) expect(s.content.length).toBeGreaterThan(200);
   });
 
+  it("offers a default init template and three named ones", () => {
+    const names = [undefined, "red", "k8s-pods", "slo"];
+    const sets = names.map((n) => grafanaPlugin.initTemplates!(n));
+    expect(new Set(sets).size).toBe(4);
+    for (const set of sets) expect(Object.keys(set.src).length).toBeGreaterThan(0);
+  });
+
   it("registers namespaced MCP contributions", async () => {
     expect(grafanaPlugin.mcpTools!().map((t) => t.name)).toEqual(["grafana:diff"]);
     const [resource] = grafanaPlugin.mcpResources!();

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,17 @@ 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 { DEFAULT_TEMPLATE, K8S_PODS_TEMPLATE, RED_TEMPLATE, SLO_TEMPLATE } from "./init-templates";
 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 +32,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 +61,8 @@ const catalogResource: McpResourceContribution = {
 export const grafanaPlugin: LexiconPlugin = {
   name: "grafana",
   serializer: grafanaSerializer,
+  configSchema: grafanaConfigSchema,
+  ownershipChannel,
 
   // ── Required lifecycle methods ────────────────────────────────
 
@@ -75,6 +102,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;
   },
@@ -97,10 +130,30 @@ export const grafanaPlugin: LexiconPlugin = {
     return [catalogResource];
   },
 
+  // `chant init --lexicon grafana [--template red|k8s-pods|slo]`; see ./init-templates.ts.
+  initTemplates(template?: string) {
+    if (template === "red") return RED_TEMPLATE;
+    if (template === "k8s-pods") return K8S_PODS_TEMPLATE;
+    if (template === "slo") return SLO_TEMPLATE;
+    return DEFAULT_TEMPLATE;
+  },
+
   detectTemplate(data: unknown) {
     return detectTemplate(data);
   },
 
+  templateParser() {
+    return new GrafanaParser();
+  },
+
+  templateGenerator() {
+    return new GrafanaGenerator();
+  },
+
+  embeddedImporters() {
+    return [dashboardImporter];
+  },
+
   completionProvider(ctx: CompletionContext) {
     return completions(ctx);
   },
@@ -109,6 +162,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);