@intentius/chant-lexicon-grafana 0.96.0

package/src/build.ts

@@ -0,0 +1,573 @@
+/**
+ * From declared entities to Grafana's own files: dashboard JSON, the
+ * datasource provisioning file and the dashboard provisioning file.
+ *
+ * Plain functions, so another lexicon (a k8s ConfigMap, a docker volume)
+ * can render the same files with `grafanaFiles()` or one dashboard with
+ * `dashboardJson()`, and the serializer is a thin wrapper around
+ * `buildGrafana()`.
+ */
+
+import { dump } from "js-yaml";
+import type { Declarable } from "@intentius/chant/declarable";
+import { isDatasourceEntity, type DatasourceEntity, type DatasourceRef } from "./datasource";
+import {
+  isDashboardEntity,
+  isDashboardProviderEntity,
+  DEFAULT_DASHBOARDS_PATH,
+  type DashboardEntity,
+  type DashboardLinkInput,
+  type DashboardProviderProps,
+} from "./dashboard";
+import { isPanelEntity, isRowEntity, type PanelEntity, type RowEntity, type PanelLink } from "./panels";
+import { isQueryEntity, type QueryEntity, type DatasourceInput } from "./query";
+import { isDatasourceVariable, isVariableEntity, type VariableEntity, type VariableHide } from "./variables";
+import type {
+  Dashboard as DashboardJson,
+  DashboardLink,
+  DataSourceRef,
+  GridPos,
+  Panel as PanelJson,
+  RowPanel as RowPanelJson,
+  VariableModel,
+} from "./schema/dashboard.gen";
+import { DASHBOARD_SCHEMA_VERSION } from "./schema/dashboard.gen";
+import { GRAFANA_SCHEMA_PIN } from "./pin";
+import { compact, slugUid } from "./util";
+
+export type { DashboardJson, PanelJson, RowPanelJson, VariableModel, DataSourceRef };
+
+/** Grafana's grid is 24 columns wide. */
+export const GRID_COLUMNS = 24;
+
+/** Where each file goes, relative to the build output directory. */
+export const DATASOURCES_FILE = "provisioning/datasources/chant.yaml";
+export const DASHBOARD_PROVIDERS_FILE = "provisioning/dashboards/chant.yaml";
+export const DASHBOARDS_DIR = "dashboards";
+
+/** One entry of `datasources:` in a provisioning file. */
+export interface ProvisionedDatasource {
+  name: string;
+  type: string;
+  uid: string;
+  access?: string;
+  url?: string;
+  isDefault?: boolean;
+  basicAuth?: boolean;
+  basicAuthUser?: string;
+  user?: string;
+  database?: string;
+  withCredentials?: boolean;
+  jsonData?: Record<string, unknown>;
+  secureJsonData?: Record<string, string>;
+  editable?: boolean;
+  orgId?: number;
+  version?: number;
+}
+
+/** One entry of `providers:` in a dashboard provisioning file. */
+export interface ProvisionedProvider {
+  name: string;
+  orgId: number;
+  folder: string;
+  folderUid?: string;
+  type: "file";
+  disableDeletion: boolean;
+  allowUiUpdates: boolean;
+  updateIntervalSeconds: number;
+  options: { path: string; foldersFromFilesStructure: boolean };
+}
+
+export interface BuiltDashboard {
+  uid: string;
+  title: string;
+  folder?: string;
+  /** Path of its JSON file, relative to the output directory. */
+  file: string;
+  json: DashboardJson;
+}
+
+export interface BuiltGrafana {
+  dashboards: BuiltDashboard[];
+  datasources: ProvisionedDatasource[];
+  providers: ProvisionedProvider[];
+  /** Every output file by path, ready to write. */
+  files: Record<string, string>;
+  /** A short summary of what was built: the serializer's primary output. */
+  index: GrafanaIndex;
+}
+
+export interface GrafanaIndex {
+  grafanaSchema: string;
+  dashboards: Array<{ uid: string; title: string; folder?: string; file: string }>;
+  datasources: Array<{ name: string; type: string; uid: string }>;
+  files: string[];
+}
+
+// ── References ──────────────────────────────────────────────────
+
+function isRef(value: unknown): value is DatasourceRef {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as DatasourceRef).type === "string" &&
+    typeof (value as DatasourceRef).uid === "string" &&
+    !("lexicon" in (value as object))
+  );
+}
+
+/** The `{ type, uid }` Grafana stores for a datasource, a datasource variable, or a ref. */
+export function datasourceRef(input: DatasourceInput | undefined): DataSourceRef | undefined {
+  if (input === undefined || input === null) return undefined;
+  if (isDatasourceEntity(input)) return { type: input.datasourceType, uid: input.uid };
+  if (isDatasourceVariable(input)) return { type: input.pluginType, uid: `\${${input.variableName}}` };
+  if (isRef(input)) return { type: input.type, uid: input.uid };
+  throw new Error("grafana: a datasource must be a Datasource, a DatasourceVariable or a { type, uid } ref");
+}
+
+function sameRef(a: DataSourceRef | undefined, b: DataSourceRef | undefined): boolean {
+  return a?.type === b?.type && a?.uid === b?.uid;
+}
+
+const MIXED: DataSourceRef = { type: "datasource", uid: "-- Mixed --" };
+
+// ── Links ───────────────────────────────────────────────────────
+
+function dashboardLink(link: DashboardLinkInput | PanelLink): DashboardLink {
+  return compact({
+    title: link.title,
+    type: link.type ?? "link",
+    url: link.url,
+    icon: link.icon ?? "external link",
+    tooltip: link.tooltip ?? "",
+    tags: link.tags ?? [],
+    asDropdown: link.asDropdown ?? false,
+    placement: link.placement,
+    targetBlank: link.targetBlank ?? false,
+    includeVars: link.includeVars ?? false,
+    keepTime: link.keepTime ?? false,
+  });
+}
+
+// ── Variables ───────────────────────────────────────────────────
+
+const HIDE: Record<VariableHide, 0 | 1 | 2> = { label: 0, valueOnly: 1, hidden: 2 };
+const REFRESH = { never: 0, onLoad: 1, onTimeRangeChange: 2 } as const;
+
+function escapeCustom(v: string): string {
+  return v.replace(/,/g, "\\,");
+}
+
+function optionsOf(values: string[], current?: { text: string | string[]; value: string | string[] }) {
+  const selected = current ? (Array.isArray(current.value) ? current.value : [current.value]) : values.slice(0, 1);
+  return values.map((v) => ({ selected: selected.includes(v), text: v, value: v }));
+}
+
+/** One variable as Grafana's `templating.list` entry. */
+export function variableModel(variable: VariableEntity): VariableModel {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const p = variable.props as any;
+  const common = {
+    type: variable.variableKind,
+    name: p.name,
+    label: p.label,
+    description: p.description,
+    hide: p.hide === undefined ? undefined : HIDE[p.hide as VariableHide],
+    skipUrlSync: p.skipUrlSync,
+  };
+  const multi = { multi: p.multi, includeAll: p.includeAll, allValue: p.allValue };
+  switch (variable.variableKind) {
+    case "query":
+      return compact({
+        ...common,
+        datasource: datasourceRef(p.datasource),
+        query: p.query,
+        definition: p.query,
+        regex: p.regex,
+        refresh: REFRESH[(p.refresh ?? "onLoad") as keyof typeof REFRESH],
+        sort: p.sort,
+        ...multi,
+        current: p.current,
+        options: [],
+      }) as VariableModel;
+    case "custom": {
+      const values: string[] = p.values;
+      const current = p.current ?? (values[0] !== undefined ? { text: values[0], value: values[0] } : undefined);
+      return compact({
+        ...common,
+        query: values.map(escapeCustom).join(","),
+        ...multi,
+        current,
+        options: optionsOf(values, current),
+      }) as VariableModel;
+    }
+    case "interval": {
+      const values: string[] = p.values;
+      const current = p.current ?? (values[0] !== undefined ? { text: values[0], value: values[0] } : undefined);
+      return compact({
+        ...common,
+        query: values.join(","),
+        current,
+        options: optionsOf(values, current),
+        auto: p.auto ?? false,
+        auto_count: p.autoCount ?? 30,
+        auto_min: p.autoMin ?? "10s",
+        refresh: 2,
+      }) as VariableModel;
+    }
+    case "datasource":
+      return compact({
+        ...common,
+        query: p.pluginType,
+        regex: p.regex ?? "",
+        ...multi,
+        current: p.current,
+        refresh: 1,
+        options: [],
+      }) as VariableModel;
+    case "constant":
+      return compact({
+        ...common,
+        hide: 2,
+        query: p.value,
+        current: { text: p.value, value: p.value },
+      }) as VariableModel;
+    case "textbox":
+      return compact({
+        ...common,
+        query: p.value ?? "",
+        current: { text: p.value ?? "", value: p.value ?? "" },
+      }) as VariableModel;
+  }
+}
+
+// ── Panels and layout ───────────────────────────────────────────
+
+function repeatName(repeat: VariableEntity | string | undefined): string | undefined {
+  if (repeat === undefined) return undefined;
+  return typeof repeat === "string" ? repeat : repeat.variableName;
+}
+
+const REF_IDS = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
+function refIdAt(i: number): string {
+  return i < REF_IDS.length ? REF_IDS[i] : `${REF_IDS[Math.floor(i / REF_IDS.length) - 1]}${REF_IDS[i % REF_IDS.length]}`;
+}
+
+/** One query as a panel target. */
+export function targetJson(query: QueryEntity, index: number, panelDatasource?: DataSourceRef): Record<string, unknown> {
+  const def = query.queryDefinition;
+  const { datasource, ...model } = query.props as Record<string, unknown> & { datasource?: DatasourceInput };
+  const ref = datasourceRef(datasource) ?? panelDatasource;
+  return compact({
+    datasource: ref,
+    refId: (model.refId as string | undefined) ?? refIdAt(index),
+    ...(def.defaults ?? {}),
+    ...model,
+  });
+}
+
+class Layout {
+  private x = 0;
+  private y = 0;
+  private lineH = 0;
+  private bottom = 0;
+
+  place(gp: Partial<GridPos> | undefined, size: { w: number; h: number }): GridPos {
+    const w = gp?.w ?? size.w;
+    const h = gp?.h ?? size.h;
+    if (gp?.x !== undefined && gp?.y !== undefined) {
+      this.bottom = Math.max(this.bottom, gp.y + h);
+      return { h, w, x: gp.x, y: gp.y };
+    }
+    if (this.x + w > GRID_COLUMNS && this.x > 0) {
+      this.y += this.lineH;
+      this.x = 0;
+      this.lineH = 0;
+    }
+    const pos = { h, w, x: this.x, y: this.y };
+    this.x += w;
+    this.lineH = Math.max(this.lineH, h);
+    this.bottom = Math.max(this.bottom, this.y + h);
+    return pos;
+  }
+
+  /** A full-width row header below everything placed so far. */
+  row(): { pos: GridPos; mark: () => void } {
+    const y = Math.max(this.bottom, this.y + this.lineH);
+    const pos = { h: 1, w: GRID_COLUMNS, x: 0, y };
+    this.x = 0;
+    this.y = y + 1;
+    this.lineH = 0;
+    this.bottom = y + 1;
+    // Called after a collapsed row's panels: the next thing starts right under the header.
+    const mark = () => {
+      this.x = 0;
+      this.y = y + 1;
+      this.lineH = 0;
+      this.bottom = y + 1;
+    };
+    return { pos, mark };
+  }
+}
+
+class Ids {
+  private next = 1;
+  constructor(private readonly taken: Set<number>) {}
+  take(explicit?: number): number {
+    if (explicit !== undefined) return explicit;
+    while (this.taken.has(this.next)) this.next++;
+    return this.next++;
+  }
+}
+
+function explicitIds(items: Array<PanelEntity | RowEntity>): Set<number> {
+  const out = new Set<number>();
+  for (const item of items) {
+    if (typeof item.props.id === "number") out.add(item.props.id);
+    if (isRowEntity(item)) for (const p of item.props.panels ?? []) if (typeof p.props.id === "number") out.add(p.props.id);
+  }
+  return out;
+}
+
+function panelJson(panel: PanelEntity, gridPos: GridPos, id: number, inherited?: DataSourceRef): PanelJson {
+  const p = panel.props;
+  const def = panel.panelDefinition;
+  const own = datasourceRef(p.datasource) ?? inherited;
+  const queries = (p.targets ?? []).filter(isQueryEntity);
+  const targets = queries.map((q, i) => targetJson(q, i, own));
+  const refs = targets.map((t) => t.datasource as DataSourceRef | undefined);
+  let datasource = own;
+  if (!datasource && refs.length > 0) {
+    datasource = refs.every((r) => sameRef(r, refs[0])) ? refs[0] : MIXED;
+  } else if (datasource && refs.some((r) => r && !sameRef(r, datasource))) {
+    datasource = MIXED;
+  }
+  const fieldConfig = {
+    defaults: { ...(p.fieldConfig?.defaults ?? {}) },
+    overrides: p.fieldConfig?.overrides ?? [],
+  };
+  return compact({
+    type: def.type,
+    id,
+    title: p.title ?? "",
+    description: p.description,
+    gridPos,
+    datasource,
+    targets: targets.length > 0 ? targets : undefined,
+    options: (p.options ?? {}) as Record<string, unknown>,
+    fieldConfig,
+    transformations: p.transformations,
+    links: p.links?.map(dashboardLink),
+    repeat: repeatName(p.repeat),
+    repeatDirection: p.repeatDirection,
+    maxPerRow: p.maxPerRow,
+    maxDataPoints: p.maxDataPoints,
+    interval: p.interval,
+    timeFrom: p.timeFrom,
+    timeShift: p.timeShift,
+    hideTimeOverride: p.hideTimeOverride,
+    transparent: p.transparent,
+    pluginVersion: p.pluginVersion,
+  }) as PanelJson;
+}
+
+/** A dashboard's `panels` array: rows and panels, laid out, with ids. */
+export function panelsJson(items: Array<PanelEntity | RowEntity>): Array<PanelJson | RowPanelJson> {
+  const layout = new Layout();
+  const ids = new Ids(explicitIds(items));
+  const out: Array<PanelJson | RowPanelJson> = [];
+  for (const item of items) {
+    if (isRowEntity(item)) {
+      const r = item.props;
+      const { pos, mark } = layout.row();
+      const rowId = ids.take(r.id);
+      const rowRef = datasourceRef(r.datasource);
+      const children = (r.panels ?? []).filter(isPanelEntity).map((p) => {
+        const gp = layout.place(p.props.gridPos, p.panelDefinition.defaultSize);
+        return panelJson(p, gp, ids.take(p.props.id), rowRef);
+      });
+      const collapsed = r.collapsed ?? false;
+      out.push(
+        compact({
+          type: "row" as const,
+          collapsed,
+          title: r.title,
+          datasource: rowRef,
+          gridPos: pos,
+          id: rowId,
+          panels: collapsed ? children : [],
+          repeat: repeatName(r.repeat),
+        }),
+      );
+      if (collapsed) mark();
+      else out.push(...children);
+    } else if (isPanelEntity(item)) {
+      const gp = layout.place(item.props.gridPos, item.panelDefinition.defaultSize);
+      out.push(panelJson(item, gp, ids.take(item.props.id)));
+    }
+  }
+  return out;
+}
+
+// ── Dashboards ──────────────────────────────────────────────────
+
+const GRAPH_TOOLTIP = { default: 0, sharedCrosshair: 1, sharedTooltip: 2 } as const;
+
+/** The dashboard's uid: its own, else from its export name, else from its title. */
+export function dashboardUid(dashboard: DashboardEntity, exportName?: string): string {
+  return dashboard.props.uid ?? slugUid(exportName ?? dashboard.props.title);
+}
+
+/** One dashboard as the JSON Grafana imports. */
+export function renderDashboard(dashboard: DashboardEntity, exportName?: string): DashboardJson {
+  const p = dashboard.props;
+  return compact({
+    annotations: { list: [] },
+    description: p.description,
+    editable: p.editable ?? true,
+    fiscalYearStartMonth: p.fiscalYearStartMonth ?? 0,
+    graphTooltip: GRAPH_TOOLTIP[p.graphTooltip ?? "default"],
+    links: (p.links ?? []).map(dashboardLink),
+    liveNow: p.liveNow,
+    panels: panelsJson(p.panels ?? []),
+    refresh: p.refresh,
+    schemaVersion: DASHBOARD_SCHEMA_VERSION,
+    tags: p.tags ?? [],
+    templating: { list: (p.variables ?? []).filter(isVariableEntity).map(variableModel) },
+    time: p.time ?? { from: "now-6h", to: "now" },
+    timepicker: p.timepicker ?? {},
+    timezone: p.timezone ?? "browser",
+    title: p.title,
+    uid: dashboardUid(dashboard, exportName),
+    weekStart: p.weekStart ?? "",
+  }) as DashboardJson;
+}
+
+/** One dashboard as formatted JSON text. */
+export function dashboardJson(dashboard: DashboardEntity, exportName?: string): string {
+  return `${JSON.stringify(renderDashboard(dashboard, exportName), null, 2)}\n`;
+}
+
+// ── Datasources and providers ───────────────────────────────────
+
+/** Replace every declared `Datasource` inside plugin settings with its uid. */
+function resolveNested(value: unknown): unknown {
+  if (isDatasourceEntity(value)) return value.uid;
+  if (Array.isArray(value)) return value.map(resolveNested);
+  if (value && typeof value === "object" && Object.getPrototypeOf(value) === Object.prototype) {
+    return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, resolveNested(v)]));
+  }
+  return value;
+}
+
+/** One datasource as a provisioning entry. */
+export function provisionedDatasource(ds: DatasourceEntity): ProvisionedDatasource {
+  const p = ds.props;
+  return compact({
+    name: p.name,
+    type: p.type,
+    uid: ds.uid,
+    access: p.access ?? "proxy",
+    url: p.url,
+    isDefault: p.isDefault,
+    basicAuth: p.basicAuth,
+    basicAuthUser: p.basicAuthUser,
+    user: p.user,
+    database: p.database,
+    withCredentials: p.withCredentials,
+    jsonData: p.jsonData === undefined ? undefined : (resolveNested(p.jsonData) as Record<string, unknown>),
+    secureJsonData: p.secureJsonData,
+    editable: p.editable ?? false,
+    orgId: p.orgId,
+    version: p.version,
+  });
+}
+
+/** One dashboard provider as a provisioning entry. */
+export function provisionedProvider(p: DashboardProviderProps): ProvisionedProvider {
+  const pinnedFolder = p.folder !== undefined || p.folderUid !== undefined;
+  return compact({
+    name: p.name,
+    orgId: p.orgId ?? 1,
+    folder: p.folder ?? "",
+    folderUid: p.folderUid,
+    type: "file" as const,
+    disableDeletion: p.disableDeletion ?? false,
+    allowUiUpdates: p.allowUiUpdates ?? false,
+    updateIntervalSeconds: p.updateIntervalSeconds ?? 30,
+    options: {
+      path: p.path ?? DEFAULT_DASHBOARDS_PATH,
+      foldersFromFilesStructure: p.foldersFromFilesStructure ?? !pinnedFolder,
+    },
+  });
+}
+
+function yamlFile(header: string, body: Record<string, unknown>): string {
+  return `# ${header}\n${dump(body, { lineWidth: -1, noRefs: true, quotingType: '"' })}`;
+}
+
+/** The datasource provisioning file for these datasources. */
+export function datasourcesYaml(datasources: ProvisionedDatasource[]): string {
+  return yamlFile("Grafana datasource provisioning, generated by chant.", { apiVersion: 1, datasources });
+}
+
+/** The dashboard provisioning file for these providers. */
+export function dashboardProvidersYaml(providers: ProvisionedProvider[]): string {
+  return yamlFile("Grafana dashboard provisioning, generated by chant.", { apiVersion: 1, providers });
+}
+
+function folderDir(folder: string): string {
+  return folder.replace(/[/\\]+/g, "-").replace(/^\.+/, "").trim() || "General";
+}
+
+// ── The whole build ─────────────────────────────────────────────
+
+/** Everything the grafana entities in a build render to. */
+export function buildGrafana(entities: Map<string, Declarable> | Iterable<Declarable>): BuiltGrafana {
+  const named: Array<[string | undefined, Declarable]> =
+    entities instanceof Map ? [...entities.entries()] : [...entities].map((e) => [undefined, e]);
+  const files: Record<string, string> = {};
+
+  // Sorted by name, so the provisioning file doesn't depend on which source file was read first.
+  const datasources = named
+    .filter(([, e]) => isDatasourceEntity(e))
+    .map(([, e]) => provisionedDatasource(e as DatasourceEntity))
+    .sort((a, b) => a.name.localeCompare(b.name));
+
+  const dashboards: BuiltDashboard[] = [];
+  for (const [name, e] of named) {
+    if (!isDashboardEntity(e)) continue;
+    const json = renderDashboard(e, name);
+    const uid = json.uid as string;
+    const folder = e.props.folder;
+    const dir = folder ? `${DASHBOARDS_DIR}/${folderDir(folder)}` : DASHBOARDS_DIR;
+    let file = `${dir}/${uid}.json`;
+    for (let n = 2; file in files; n++) file = `${dir}/${uid}-${n}.json`;
+    files[file] = `${JSON.stringify(json, null, 2)}\n`;
+    dashboards.push({ uid, title: e.props.title, ...(folder ? { folder } : {}), file, json });
+  }
+
+  const declaredProviders = named.filter(([, e]) => isDashboardProviderEntity(e)).map(([, e]) => (e as unknown as { props: DashboardProviderProps }).props);
+  const providers =
+    declaredProviders.length > 0
+      ? declaredProviders.map(provisionedProvider)
+      : dashboards.length > 0
+        ? [provisionedProvider({ name: "chant" })]
+        : [];
+
+  if (datasources.length > 0) files[DATASOURCES_FILE] = datasourcesYaml(datasources);
+  if (providers.length > 0) files[DASHBOARD_PROVIDERS_FILE] = dashboardProvidersYaml(providers);
+
+  const index: GrafanaIndex = {
+    grafanaSchema: `${GRAFANA_SCHEMA_PIN.source}@${GRAFANA_SCHEMA_PIN.ref}`,
+    dashboards: dashboards.map(({ uid, title, folder, file }) => ({ uid, title, ...(folder ? { folder } : {}), file })),
+    datasources: datasources.map(({ name, type, uid }) => ({ name, type, uid })),
+    files: Object.keys(files).sort(),
+  };
+  return { dashboards, datasources, providers, files, index };
+}
+
+/** Every file the grafana entities render to, by path relative to the output directory. */
+export function grafanaFiles(entities: Map<string, Declarable> | Iterable<Declarable>): Record<string, string> {
+  return buildGrafana(entities).files;
+}

package/src/catalog.ts

@@ -0,0 +1,116 @@
+/**
+ * The built-in entity catalog: every class this package exports, keyed by
+ * class name. It feeds the packaged registry (`dist/meta.json`), LSP
+ * completions and hover, and the docs.
+ */
+
+import type { LexiconEntry } from "@intentius/chant/lsp/lexicon-providers";
+import { DATASOURCE_TYPE } from "./datasource";
+import { DASHBOARD_TYPE, DASHBOARD_PROVIDER_TYPE } from "./dashboard";
+import * as panels from "./panels";
+import * as queries from "./query";
+import { VARIABLE_TYPE_PREFIX } from "./variables";
+
+export type CatalogKind = "dashboard" | "datasource" | "provider" | "panel" | "row" | "query" | "variable";
+
+export interface CatalogEntry {
+  className: string;
+  entityType: string;
+  kind: CatalogKind;
+  /** Resource entities are emitted; property entities live inside one. */
+  entityKind: "resource" | "property";
+  /** The Grafana plugin id, for panels and queries. */
+  pluginId?: string;
+  description: string;
+}
+
+function isClassWith<T>(v: unknown, key: string): v is { definition: T } {
+  return typeof v === "function" && typeof (v as unknown as Record<string, unknown>)[key] === "object";
+}
+
+const panelEntries: CatalogEntry[] = (Object.entries(panels) as Array<[string, unknown]>)
+  .filter((e): e is [string, panels.PanelClass] => isClassWith<panels.PanelDefinition>(e[1], "definition"))
+  .map(([className, cls]) => ({
+    className,
+    entityType: `${panels.PANEL_TYPE_PREFIX}${cls.definition.type}`,
+    kind: "panel",
+    entityKind: "property",
+    pluginId: cls.definition.type,
+    description: cls.definition.description ?? "",
+  }));
+
+const queryEntries: CatalogEntry[] = (Object.entries(queries) as Array<[string, unknown]>)
+  .filter((e): e is [string, queries.QueryClass] => isClassWith<queries.QueryDefinition>(e[1], "definition"))
+  .map(([className, cls]) => ({
+    className,
+    entityType: `${queries.QUERY_TYPE_PREFIX}${cls.definition.datasourceType}`,
+    kind: "query",
+    entityKind: "property",
+    pluginId: cls.definition.datasourceType,
+    description: cls.definition.description ?? "",
+  }));
+
+const VARIABLES: Array<[string, string, string]> = [
+  ["QueryVariable", "query", "A variable whose values come from a datasource query"],
+  ["CustomVariable", "custom", "A variable with a fixed list of values"],
+  ["IntervalVariable", "interval", "A time interval to choose, for range selectors"],
+  ["DatasourceVariable", "datasource", "A choice of datasource of one plugin type; usable wherever a datasource is"],
+  ["ConstantVariable", "constant", "A hidden, fixed value"],
+  ["TextboxVariable", "textbox", "A free-text box"],
+];
+
+export const BUILTIN_CATALOG: CatalogEntry[] = [
+  {
+    className: "Dashboard",
+    entityType: DASHBOARD_TYPE,
+    kind: "dashboard",
+    entityKind: "resource",
+    description: "A dashboard: title, uid, time range, variables, rows, panels and links, written as the JSON Grafana imports",
+  },
+  {
+    className: "Datasource",
+    entityType: DATASOURCE_TYPE,
+    kind: "datasource",
+    entityKind: "resource",
+    description: "A datasource, declared once and referenced by panels, queries and variables",
+  },
+  {
+    className: "DashboardProvider",
+    entityType: DASHBOARD_PROVIDER_TYPE,
+    kind: "provider",
+    entityKind: "resource",
+    description: "An entry in the dashboard provisioning file; a default one is written when none is declared",
+  },
+  {
+    className: "Row",
+    entityType: panels.ROW_TYPE,
+    kind: "row",
+    entityKind: "property",
+    description: "A full-width row header; its panels are placed below it, or inside it when collapsed",
+  },
+  ...panelEntries,
+  ...queryEntries,
+  ...VARIABLES.map(
+    ([className, type, description]): CatalogEntry => ({
+      className,
+      entityType: `${VARIABLE_TYPE_PREFIX}${type}`,
+      kind: "variable",
+      entityKind: "property",
+      description,
+    }),
+  ),
+];
+
+/**
+ * The catalog as a chant lexicon registry, keyed by class name. Every class
+ * is listed as a resource, including the property-kind panels, queries and
+ * variables: the registry drives `new …` completions, and an author writes
+ * `new TimeSeriesPanel(…)` the same way as `new Dashboard(…)`.
+ */
+export function lexiconRegistry(): Record<string, LexiconEntry> {
+  const out: Record<string, LexiconEntry> = {};
+  for (const e of [...BUILTIN_CATALOG].sort((a, b) => a.className.localeCompare(b.className))) {
+    out[e.className] = { resourceType: e.entityType, kind: "resource", lexicon: "grafana" };
+  }
+  return out;
+}

package/src/codegen/docs-cli.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env tsx
+import { generateDocs } from "./docs";
+
+await generateDocs({ verbose: true });