@intentius/chant-lexicon-grafana 0.96.0

package/src/lsp/hover.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from "vitest";
+import { hover } from "./hover";
+
+describe("grafana LSP hover", () => {
+  it("describes a panel and its plugin id", () => {
+    const info = hover({
+      uri: "file:///dashboard.ts",
+      content: "new StatPanel({})",
+      position: { line: 0, character: 6 },
+      word: "StatPanel",
+      lineText: "new StatPanel({})",
+    });
+    expect(info?.contents).toContain("Grafana::Panel::stat");
+    expect(info?.contents).toContain("Panel plugin `stat`");
+  });
+
+  it("describes a query and its datasource type", () => {
+    const info = hover({ uri: "file:///q.ts", content: "new TempoQuery({})", position: { line: 0, character: 6 }, word: "TempoQuery", lineText: "new TempoQuery({})" });
+    expect(info?.contents).toContain("`tempo` datasources");
+  });
+
+  it("returns undefined for an unknown word", () => {
+    expect(hover({ uri: "file:///x.ts", content: "", position: { line: 0, character: 0 }, word: "Nope", lineText: "" })).toBeUndefined();
+  });
+});

package/src/lsp/hover.ts

@@ -0,0 +1,28 @@
+import type { HoverContext, HoverInfo } from "@intentius/chant/lsp/types";
+import { LexiconIndex, lexiconHover, type LexiconEntry } from "@intentius/chant/lsp/lexicon-providers";
+import { BUILTIN_CATALOG, lexiconRegistry } from "../catalog";
+import { GRAFANA_SCHEMA_PIN } from "../pin";
+
+let cachedIndex: LexiconIndex | null = null;
+
+function getIndex(): LexiconIndex {
+  cachedIndex ??= new LexiconIndex(lexiconRegistry());
+  return cachedIndex;
+}
+
+/** Hover for grafana entity classes: what it declares and, for panels and queries, the Grafana plugin id. */
+export function hover(ctx: HoverContext): HoverInfo | undefined {
+  return lexiconHover(ctx, getIndex(), resourceHover);
+}
+
+function resourceHover(className: string, entry: LexiconEntry): HoverInfo | undefined {
+  const cat = BUILTIN_CATALOG.find((c) => c.className === className);
+  const lines = [`**${className}**`, "", `grafana type: \`${entry.resourceType}\``];
+  if (cat?.description) lines.push("", cat.description);
+  if (cat?.kind === "panel") {
+    lines.push("", `Panel plugin \`${cat.pluginId}\`. Options typed from ${GRAFANA_SCHEMA_PIN.source} ${GRAFANA_SCHEMA_PIN.ref}.`);
+  } else if (cat?.kind === "query") {
+    lines.push("", `For \`${cat.pluginId}\` datasources. Typed from ${GRAFANA_SCHEMA_PIN.source} ${GRAFANA_SCHEMA_PIN.ref}.`);
+  }
+  return { contents: lines.join("\n") };
+}

package/src/package-cli.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env tsx
+/**
+ * Thin entry point for `npm run bundle` in lexicon-grafana.
+ */
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { writeBundleSpec } from "@intentius/chant/codegen/package";
+import { generate, writeGeneratedFiles } from "./codegen/generate";
+import { packageLexicon } from "./codegen/package";
+
+const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+
+writeGeneratedFiles(await generate({ verbose: true }));
+const { spec, stats } = await packageLexicon({ verbose: true });
+writeBundleSpec(spec, join(pkgDir, "dist"));
+
+console.error(`Packaged ${stats.resources} entities, ${stats.ruleCount} rules, ${stats.skillCount} skills`);

package/src/panels.ts

@@ -0,0 +1,275 @@
+/**
+ * Panels and rows.
+ *
+ * Each built-in panel class is defined through `definePanel`, with its
+ * `options` and `fieldConfig.defaults.custom` typed from that panel's
+ * schema at `GRAFANA_SCHEMA_PIN`. Every option is optional: Grafana fills
+ * in what a panel leaves out when it loads the dashboard. A panel plugin
+ * chant doesn't ship (a community visualization, an in-house plugin) comes
+ * in through `definePanel` too and is laid out, serialized and checked the
+ * same way.
+ *
+ * `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.
+ */
+
+import { createProperty } from "@intentius/chant/runtime";
+import type { Declarable } from "@intentius/chant/declarable";
+import type { DeepPartial } from "./util";
+import type { DatasourceInput, QueryEntity } from "./query";
+import type { VariableEntity } from "./variables";
+import type { SchemaName } from "./pin";
+import type {
+  DashboardLink,
+  DataTransformerConfig,
+  FieldConfig,
+  FieldConfigSource,
+  GridPos,
+} from "./schema/dashboard.gen";
+import type * as timeseries from "./schema/timeseries.gen";
+import type * as stat from "./schema/stat.gen";
+import type * as gauge from "./schema/gauge.gen";
+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";
+
+/** `fieldConfig` with `defaults.custom` typed for the panel. */
+export interface PanelFieldConfig<C> {
+  defaults?: DeepPartial<Omit<FieldConfig, "custom">> & { custom?: DeepPartial<C> };
+  overrides?: FieldConfigSource["overrides"];
+}
+
+/** A panel link: Grafana's `DashboardLink` fields, all but `title` optional. */
+export type PanelLink = Partial<DashboardLink> & { title: string; url?: string };
+
+export interface PanelProps<O = Record<string, unknown>, C = Record<string, unknown>> {
+  title?: string;
+  description?: string;
+  /** Position and size in the 24-column grid. Leave out `x`/`y` to let the dashboard place it. */
+  gridPos?: Partial<GridPos>;
+  /** The datasource for every query that doesn't name its own. */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  datasource?: DatasourceInput<any>;
+  /** The panel's queries. `refId`s default to A, B, C… in order. */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  targets?: QueryEntity<any, any>[];
+  /** The panel plugin's own options, typed from its schema. */
+  options?: DeepPartial<O>;
+  fieldConfig?: PanelFieldConfig<C>;
+  transformations?: DataTransformerConfig[];
+  links?: PanelLink[];
+  /** Repeat the panel once per value of this variable. */
+  repeat?: VariableEntity | string;
+  repeatDirection?: "h" | "v";
+  maxPerRow?: number;
+  maxDataPoints?: number;
+  interval?: string;
+  timeFrom?: string;
+  timeShift?: string;
+  hideTimeOverride?: boolean;
+  transparent?: boolean;
+  pluginVersion?: string;
+  /** Panel id within the dashboard. Defaults to position order, 1, 2, 3… */
+  id?: number;
+}
+
+export interface PanelDefinition<T extends string = string> {
+  /** The panel plugin id Grafana stores in `type`. */
+  type: T;
+  className: string;
+  description?: string;
+  /** Size used when `gridPos` leaves `w` or `h` out. */
+  defaultSize: { w: number; h: number };
+  /** The vendored schema its options follow, when there is one (GRAF107 validates against it). */
+  schema?: SchemaName;
+  /** True only for the panels this package ships. */
+  builtin: boolean;
+}
+
+export interface PanelEntity<O = Record<string, unknown>, C = Record<string, unknown>> extends Declarable {
+  readonly props: PanelProps<O, C>;
+  readonly panelDefinition: PanelDefinition;
+}
+
+export interface PanelClass<T extends string = string, O = Record<string, unknown>, C = Record<string, unknown>> {
+  new (props?: PanelProps<O, C>): PanelEntity<O, C>;
+  readonly definition: PanelDefinition<T>;
+}
+
+export const PANEL_TYPE_PREFIX = "Grafana::Panel::";
+export const ROW_TYPE = "Grafana::Row";
+
+const REGISTRY_KEY = Symbol.for("chant.grafana.panelDefinitions");
+function registry(): Map<string, PanelDefinition> {
+  const g = globalThis as unknown as Record<symbol, Map<string, PanelDefinition> | undefined>;
+  return (g[REGISTRY_KEY] ??= new Map());
+}
+
+/** Every registered panel definition, built-ins first. */
+export function registeredPanels(): PanelDefinition[] {
+  return [...registry().values()];
+}
+
+export function panelDefinitionFor(type: string): PanelDefinition | undefined {
+  return registry().get(type);
+}
+
+const PLUGIN_ID = /^[a-z0-9][a-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.type === "row") throw new Error('grafana: "row" is not a panel; use Row');
+  const existing = registry().get(def.type);
+  if (existing?.builtin && !def.builtin) {
+    throw new Error(`grafana: the "${def.type}" panel is built in (${existing.className}); use that class.`);
+  }
+  registry().set(def.type, def);
+  const Base = createProperty(`${PANEL_TYPE_PREFIX}${def.type}`, "grafana") as unknown as (
+    this: object,
+    props: Record<string, unknown>,
+  ) => void;
+  const Cls = function (this: object, props?: Record<string, unknown>) {
+    Base.call(this, props ?? {});
+    Object.defineProperty(this, "panelDefinition", { value: def, enumerable: false });
+  };
+  Object.defineProperty(Cls, "name", { value: def.className });
+  Object.defineProperty(Cls, "definition", { value: def, enumerable: false });
+  return Cls as unknown as PanelClass<T, O, C>;
+}
+
+/**
+ * Define a panel class for a panel plugin chant doesn't ship.
+ *
+ * @example
+ * ```ts
+ * interface PieOptions { pieType?: "pie" | "donut"; legend?: { showLegend?: boolean } }
+ *
+ * export const PieChartPanel = definePanel<PieOptions>()({
+ *   type: "piechart",
+ *   className: "PieChartPanel",
+ *   defaultSize: { w: 8, h: 8 },
+ * });
+ * ```
+ */
+export function definePanel<O = Record<string, unknown>, C = Record<string, unknown>>() {
+  return function <T extends string>(def: Omit<PanelDefinition<T>, "builtin">): PanelClass<T, O, C> {
+    return makePanelClass<T, O, C>({ ...def, builtin: false });
+  };
+}
+
+export function isPanelEntity(value: unknown): value is PanelEntity {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as Declarable).lexicon === "grafana" &&
+    typeof (value as Declarable).entityType === "string" &&
+    (value as Declarable).entityType.startsWith(PANEL_TYPE_PREFIX)
+  );
+}
+
+// ── Built-in panels ─────────────────────────────────────────────
+
+export const TimeSeriesPanel = makePanelClass<"timeseries", timeseries.Options, timeseries.FieldConfig>({
+  type: "timeseries",
+  className: "TimeSeriesPanel",
+  description: "Time series: values over time as lines, bars or points",
+  defaultSize: { w: 12, h: 8 },
+  schema: "timeseries",
+  builtin: true,
+});
+
+export const StatPanel = makePanelClass<"stat", stat.Options, Record<string, unknown>>({
+  type: "stat",
+  className: "StatPanel",
+  description: "Stat: one big number per series, with an optional sparkline",
+  defaultSize: { w: 6, h: 4 },
+  schema: "stat",
+  builtin: true,
+});
+
+export const GaugePanel = makePanelClass<"gauge", gauge.Options, Record<string, unknown>>({
+  type: "gauge",
+  className: "GaugePanel",
+  description: "Gauge: a value against its min, max and thresholds",
+  defaultSize: { w: 6, h: 6 },
+  schema: "gauge",
+  builtin: true,
+});
+
+export const TablePanel = makePanelClass<"table", table.Options, table.FieldConfig>({
+  type: "table",
+  className: "TablePanel",
+  description: "Table: query results as rows and columns",
+  defaultSize: { w: 12, h: 8 },
+  schema: "table",
+  builtin: true,
+});
+
+export const LogsPanel = makePanelClass<"logs", logs.Options, Record<string, unknown>>({
+  type: "logs",
+  className: "LogsPanel",
+  description: "Logs: log lines from a logs datasource such as Loki",
+  defaultSize: { w: 24, h: 10 },
+  schema: "logs",
+  builtin: true,
+});
+
+export const TracesPanel = makePanelClass<"traces", Record<string, unknown>, Record<string, unknown>>({
+  type: "traces",
+  className: "TracesPanel",
+  description: "Traces: one trace as a span timeline, from a tracing datasource such as Tempo",
+  defaultSize: { w: 24, h: 12 },
+  builtin: true,
+});
+
+export const HeatmapPanel = makePanelClass<"heatmap", heatmap.Options, heatmap.FieldConfig>({
+  type: "heatmap",
+  className: "HeatmapPanel",
+  description: "Heatmap: a distribution over time, e.g. histogram buckets",
+  defaultSize: { w: 12, h: 8 },
+  schema: "heatmap",
+  builtin: true,
+});
+
+export const TextPanel = makePanelClass<"text", text.Options, Record<string, unknown>>({
+  type: "text",
+  className: "TextPanel",
+  description: "Text: markdown or HTML, no queries",
+  defaultSize: { w: 24, h: 3 },
+  schema: "text",
+  builtin: true,
+});
+
+// ── Rows ────────────────────────────────────────────────────────
+
+export interface RowProps {
+  title: string;
+  /** Collapsed rows keep their panels inside the row until opened. */
+  collapsed?: boolean;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  panels?: PanelEntity<any, any>[];
+  /** Repeat the row once per value of this variable. */
+  repeat?: VariableEntity | string;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  datasource?: DatasourceInput<any>;
+  id?: number;
+}
+
+export interface RowEntity extends Declarable {
+  readonly props: RowProps;
+}
+
+const RowBase = createProperty(ROW_TYPE, "grafana") as unknown as (this: object, props: Record<string, unknown>) => void;
+
+/** A full-width row header; the panels listed in it are placed below it. */
+export const Row = function (this: object, props: RowProps) {
+  RowBase.call(this, props as unknown as Record<string, unknown>);
+} as unknown as new (props: RowProps) => RowEntity;
+Object.defineProperty(Row, "name", { value: "Row" });
+
+export function isRowEntity(value: unknown): value is RowEntity {
+  return typeof value === "object" && value !== null && (value as Declarable).entityType === ROW_TYPE && (value as Declarable).lexicon === "grafana";
+}

package/src/pin.ts

@@ -0,0 +1,68 @@
+/**
+ * The Grafana schemas this lexicon's types are generated from.
+ *
+ * Grafana defines dashboards, panel options and datasource queries as CUE
+ * 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.
+ *
+ * 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/`.
+ */
+
+export interface GrafanaSchemaPin {
+  /** Where the schema files come from. */
+  source: string;
+  /** The tag the commit is published under. */
+  ref: string;
+  /** The exact commit the vendored files were taken from. */
+  commit: string;
+  /** The Grafana kind registry version cog generated the schemas from. */
+  kindRegistry: string;
+  /** sha256 of each vendored file, keyed by schema name (`src/spec/schemas/<name>.jsonschema.json`). */
+  files: Readonly<Record<SchemaName, string>>;
+}
+
+export const SCHEMA_NAMES = [
+  "dashboard",
+  "timeseries",
+  "stat",
+  "gauge",
+  "table",
+  "logs",
+  "heatmap",
+  "text",
+  "prometheus",
+  "tempo",
+  "loki",
+] as const;
+
+export type SchemaName = (typeof SCHEMA_NAMES)[number];
+
+export const GRAFANA_SCHEMA_PIN: GrafanaSchemaPin = Object.freeze({
+  source: "github.com/grafana/grafana-foundation-sdk/jsonschema",
+  ref: "v0.0.20",
+  commit: "d9e3417a1a40a0b42379cedbd270411e599fa492",
+  kindRegistry: "v11.6.x",
+  files: Object.freeze({
+    dashboard: "67451cd5b288f97e3f68eccd52ffa4f75151fc87c669b8cd93c051056b294265",
+    timeseries: "77ba36d66bbfcb363eeb5e6957813ca4b4cbc5a5bc4e8a12034d4c3b8cbbbde4",
+    stat: "da547c8b1e52883a77e876f34d90d6034266ca8488a5601900ca26fc01d74b9e",
+    gauge: "154f065b05b36c84ff1b372edc2c7ef5a5dde32adec77daddf6bf9fab726eb96",
+    table: "eeaf780eb1be6fcd2ff0c098a1ba6eb051a8a37a0b2ea8db7c4d3bcdc5db6b97",
+    logs: "0254600ef9720bd2c906628304a7c362c0182b4bff2fd7d91352d95a269b2dda",
+    heatmap: "1e1905eef14ada48c121374ecad41412380b317e8183771d99a7504753d5005c",
+    text: "db6d2e3e2c576d1c78ac2e08930f60dbc22bb7ee21abd0cd9204be49f0dbce09",
+    prometheus: "726fc97eeb1e37791dbbf988c3cf40de17bb8e623926e6979c4a3f947cb1af87",
+    tempo: "21aec4c333c9b8e5e9228e85a6225c76161975abb54002e6f12e919e3b4e54ae",
+    loki: "03b81d6b952e3d31785c4b52637e2b7b1c170cc2ea8ec7ec671c21599508e31b",
+  }),
+});
+
+/** The raw URL of one schema file at the pinned commit. */
+export function schemaUrl(name: SchemaName, 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

@@ -0,0 +1,50 @@
+import { describe, expect, it } from "vitest";
+import { isLexiconPlugin } from "@intentius/chant/lexicon";
+import { grafanaPlugin } from "./plugin";
+import { grafanaAuditCatalog } from "./lint/audit-catalog";
+
+describe("grafana plugin", () => {
+  it("is a valid LexiconPlugin", () => {
+    expect(isLexiconPlugin(grafanaPlugin)).toBe(true);
+  });
+
+  it("is named grafana and serializes under the GRAF prefix", () => {
+    expect(grafanaPlugin.name).toBe("grafana");
+    expect(grafanaPlugin.serializer.name).toBe("grafana");
+    expect(grafanaPlugin.serializer.rulePrefix).toBe("GRAF");
+  });
+
+  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"]);
+  });
+
+  it("catalogues every rule and check for chant audit, and nothing else", () => {
+    const ids = [...grafanaPlugin.lintRules!().map((r) => r.id), ...grafanaPlugin.postSynthChecks!().map((c) => c.id)];
+    expect(Object.keys(grafanaAuditCatalog).sort()).toEqual([...ids].sort());
+    for (const check of grafanaPlugin.postSynthChecks!()) expect(grafanaAuditCatalog[check.id].yamlBased).toBe(true);
+  });
+
+  it("detects dashboards and provisioning files and nothing else", () => {
+    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: "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"]);
+    for (const s of skills) expect(s.content.length).toBeGreaterThan(200);
+  });
+
+  it("registers namespaced MCP contributions", async () => {
+    expect(grafanaPlugin.mcpTools!().map((t) => t.name)).toEqual(["grafana:diff"]);
+    const [resource] = grafanaPlugin.mcpResources!();
+    expect(resource.uri).toBe("grafana:resource-catalog");
+    const body = JSON.parse(await resource.handler());
+    expect(body.pin.commit).toMatch(/^[0-9a-f]{40}$/);
+    expect(body.entities.map((e: { className: string }) => e.className)).toContain("TimeSeriesPanel");
+  });
+});

package/src/plugin.ts

@@ -0,0 +1,116 @@
+import type { LexiconPlugin } from "@intentius/chant/lexicon";
+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";
+import { grafanaSerializer } from "./serializer";
+import { rules } from "./lint/rules";
+import { postSynthChecks } from "./lint/post-synth";
+import { grafanaAuditCatalog } from "./lint/audit-catalog";
+import { completions } from "./lsp/completions";
+import { hover } from "./lsp/hover";
+import { detectTemplate } from "./detect";
+import { grafanaSkills } from "./skill-defs";
+import { BUILTIN_CATALOG } from "./catalog";
+import { GRAFANA_SCHEMA_PIN } from "./pin";
+import { compositeCatalog } from "./composites/catalog";
+
+const catalogResource: McpResourceContribution = {
+  uri: "grafana:resource-catalog",
+  name: "Grafana entity catalog",
+  description: "The dashboard, datasource, panel, query and variable classes this lexicon types, with the Grafana schema pin they follow",
+  mimeType: "application/json",
+  async handler(): Promise<string> {
+    return JSON.stringify({ pin: GRAFANA_SCHEMA_PIN, entities: BUILTIN_CATALOG });
+  },
+};
+
+/**
+ * Grafana lexicon plugin.
+ *
+ * Dashboards, panels, typed Prometheus, Tempo and Loki queries, variables
+ * and datasources, serialized to dashboard JSON and Grafana's provisioning
+ * files. Panel options and query models are generated from Grafana's own
+ * schemas at `GRAFANA_SCHEMA_PIN`; `definePanel` and `defineQuery` add
+ * plugins chant doesn't ship.
+ */
+export const grafanaPlugin: LexiconPlugin = {
+  name: "grafana",
+  serializer: grafanaSerializer,
+
+  // ── Required lifecycle methods ────────────────────────────────
+
+  async generate(options?: { verbose?: boolean }): Promise<void> {
+    const { generate, writeGeneratedFiles } = await import("./codegen/generate");
+    writeGeneratedFiles(await generate(options));
+  },
+
+  async validate(_options?: { verbose?: boolean }): Promise<void> {
+    const { validate } = await import("./validate");
+    const { printValidationResult } = await import("@intentius/chant/codegen/validate");
+    printValidationResult(await validate());
+  },
+
+  async coverage(_options?: { verbose?: boolean; minOverall?: number }): Promise<void> {
+    const byKind = new Map<string, string[]>();
+    for (const c of BUILTIN_CATALOG) byKind.set(c.kind, [...(byKind.get(c.kind) ?? []), c.pluginId ?? c.className]);
+    console.error(`grafana: ${BUILTIN_CATALOG.length} entity classes, typed against ${GRAFANA_SCHEMA_PIN.source} ${GRAFANA_SCHEMA_PIN.ref}`);
+    for (const [kind, names] of byKind) console.error(`  ${kind}: ${names.join(", ")}`);
+    console.error("  other panel and datasource plugins: definePanel, defineQuery");
+  },
+
+  async package(options?: { verbose?: boolean; force?: boolean }): Promise<void> {
+    const { packageLexicon } = await import("./codegen/package");
+    const { writeBundleSpec } = await import("@intentius/chant/codegen/package");
+    const { join, dirname } = await import("path");
+    const { fileURLToPath } = await import("url");
+    const { spec, stats } = await packageLexicon(options);
+    const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+    writeBundleSpec(spec, join(pkgDir, "dist"));
+    console.error(`Packaged ${stats.resources} entities, ${stats.ruleCount} rules, ${stats.skillCount} skills`);
+  },
+
+  // ── Optional extensions ────────────────────────────────────
+
+  lintRules() {
+    return rules;
+  },
+
+  postSynthChecks() {
+    return postSynthChecks;
+  },
+
+  auditCatalog() {
+    return grafanaAuditCatalog;
+  },
+
+  skills: grafanaSkills,
+
+  composites() {
+    return compositeCatalog;
+  },
+
+  mcpTools() {
+    return [createDiffTool(grafanaSerializer, "Compare current Grafana dashboard and provisioning output against the previous build", "grafana")];
+  },
+
+  mcpResources() {
+    return [catalogResource];
+  },
+
+  detectTemplate(data: unknown) {
+    return detectTemplate(data);
+  },
+
+  completionProvider(ctx: CompletionContext) {
+    return completions(ctx);
+  },
+
+  hoverProvider(ctx: HoverContext) {
+    return hover(ctx);
+  },
+
+  async docs(options?: { verbose?: boolean }) {
+    const { generateDocs } = await import("./codegen/docs");
+    return generateDocs(options);
+  },
+};