@intentius/chant-lexicon-grafana 0.97.0 → 0.99.0

package/src/import/live-export.ts

@@ -0,0 +1,264 @@
+/**
+ * Live Grafana objects -> chant's vocabulary, pure (#2946).
+ *
+ * Two consumers, one mapping:
+ *
+ * - live export (`../export-resources.ts`) turns dashboards and
+ *   datasources read over the API into `TemplateIR` that feeds
+ *   `templateGenerator()` unchanged;
+ * - deep observation (`../deep-observe.ts`) turns one live dashboard into
+ *   the property tree core diffs against the declaration.
+ *
+ * Both go through the importer (`./parser.ts`), so a dashboard read from
+ * Grafana and a dashboard file given to `chant import` become the same
+ * declarations. The importer is not changed here; this module only reads
+ * the plan it makes.
+ *
+ * ## Why the drift tree is in chant's vocabulary, not Grafana's
+ *
+ * Core diffs a declaration's `props` (with property-kind declarables, which
+ * panels, rows, queries and variables are, inlined as their own props)
+ * against the tree a reader returns. A `Dashboard`'s props are what the
+ * author wrote: `graphTooltip: "sharedCrosshair"`, `panels: [Row, ...]`, a
+ * query with no `refId`. The JSON Grafana stores is what the build wrote
+ * from them: `graphTooltip: 1`, a flat panel list, `refId: "A"`. So the
+ * live side has to be put into the author's vocabulary, and the importer
+ * is exactly that translation, already tested to round-trip. Reading the
+ * plan back as one tree (every reference replaced by what it refers to)
+ * gives the live counterpart of the declared tree.
+ *
+ * What the translation cannot decide on its own (a panel `id` the build
+ * numbered, a `gridPos` it laid out, the built-in annotation Grafana adds)
+ * is noise, and noise is named in `../deep-observe-hooks.ts`, which core
+ * applies to both trees.
+ */
+
+import type { ResourceIR, TemplateIR } from "@intentius/chant/import/parser";
+import { isDeclRef, type Declaration, type Plan } from "./model";
+import {
+  DASHBOARD_RESOURCE_TYPE,
+  PROVISIONING_RESOURCE_TYPE,
+  planDashboard,
+  planDatasourceProvisioning,
+  type DashboardResourceMetadata,
+  type PlanResourceProperties,
+} from "./parser";
+
+type Json = Record<string, unknown>;
+
+function isObject(v: unknown): v is Json {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/**
+ * The dashboard declaration of a plan as one property tree: each reference
+ * replaced by the props (or, for a `DatasourceRef` const, the value) of the
+ * declaration it names, the way core inlines a property-kind declarable.
+ */
+export function planTree(plan: Plan): Json {
+  const byId = new Map<string, Declaration>(plan.declarations.map((d) => [d.id, d]));
+  const resolve = (value: unknown, seen: ReadonlySet<string>): unknown => {
+    if (isDeclRef(value)) {
+      const decl = byId.get(value.$decl);
+      if (!decl || seen.has(decl.id)) return undefined;
+      const next = new Set(seen).add(decl.id);
+      return resolve(decl.kind === "value" ? decl.value : (decl.props ?? {}), next);
+    }
+    if (Array.isArray(value)) return value.map((v) => resolve(v, seen)).filter((v) => v !== undefined);
+    if (isObject(value)) {
+      const out: Json = {};
+      for (const [k, v] of Object.entries(value)) {
+        const r = resolve(v, seen);
+        if (r !== undefined) out[k] = r;
+      }
+      return out;
+    }
+    return value;
+  };
+  const dashboard = byId.get("dashboard");
+  if (!dashboard) return {};
+  return resolve(dashboard.props ?? {}, new Set(["dashboard"])) as Json;
+}
+
+/** One live dashboard (classic JSON) as the property tree core diffs a `Dashboard` declaration against. */
+export function dashboardTree(dashboard: Json): { tree: Json; warnings: string[] } {
+  const { plan, warnings } = planDashboard(dashboard);
+  return { tree: planTree(plan), warnings };
+}
+
+/** The keys a datasource's props take (`DatasourceProps`), in the order they are written. */
+export const DATASOURCE_PROP_KEYS: readonly string[] = [
+  "name",
+  "type",
+  "uid",
+  "url",
+  "access",
+  "isDefault",
+  "basicAuth",
+  "basicAuthUser",
+  "user",
+  "database",
+  "withCredentials",
+  "jsonData",
+  "secureJsonData",
+  "editable",
+  "orgId",
+  "version",
+];
+
+/**
+ * Grafana's value for a datasource key the API always returns, where it
+ * means "not set". Export leaves these out so the generated source says what
+ * somebody chose, as a provisioning file would.
+ */
+export const DATASOURCE_API_DEFAULTS: Readonly<Json> = {
+  access: "proxy",
+  isDefault: false,
+  basicAuth: false,
+  basicAuthUser: "",
+  user: "",
+  database: "",
+  withCredentials: false,
+  jsonData: {},
+};
+
+/**
+ * One datasource from `GET /api/datasources[/uid/<uid>]` in `DatasourceProps`
+ * vocabulary.
+ *
+ * - `readOnly` (the API's word) becomes `editable` (the provisioning file's).
+ * - `secureJsonFields` names which secrets are set and never their values;
+ *   they become `secureJsonData` keys whose value is `[REDACTED]`, so the
+ *   key set compares and nothing secret is ever held.
+ * - `id`, `orgId`, `version`, `typeName`, `typeLogoUrl`, `apiVersion` and the
+ *   rest are the server's own and are left out.
+ *
+ * `keepDefaults` keeps keys at the API's "not set" value (`--verbatim`).
+ */
+export function datasourceProps(live: Json, options: { keepDefaults?: boolean } = {}): Json {
+  const out: Json = {};
+  for (const key of DATASOURCE_PROP_KEYS) {
+    if (key === "secureJsonData" || key === "editable" || key === "orgId" || key === "version") continue;
+    const v = live[key];
+    if (v === undefined || v === null) continue;
+    if (!options.keepDefaults && key in DATASOURCE_API_DEFAULTS && deepEqualJson(v, DATASOURCE_API_DEFAULTS[key])) continue;
+    out[key] = v;
+  }
+  const secure = isObject(live.secureJsonFields) ? Object.keys(live.secureJsonFields).filter((k) => live.secureJsonFields && (live.secureJsonFields as Json)[k] === true) : [];
+  if (secure.length > 0) out.secureJsonData = Object.fromEntries(secure.sort().map((k) => [k, "[REDACTED]"]));
+  if (typeof live.readOnly === "boolean") {
+    const editable = !live.readOnly;
+    if (editable || options.keepDefaults) out.editable = editable;
+  }
+  return out;
+}
+
+function deepEqualJson(a: unknown, b: unknown): boolean {
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+
+// ── export ──────────────────────────────────────────────────────────
+
+/**
+ * A dashboard plan whose `ExternalDatasource`s for the given uids are
+ * written as plain `{ type, uid }` refs instead.
+ *
+ * The importer declares an `ExternalDatasource` for each datasource a
+ * dashboard names, because a dashboard file alone does not say where its
+ * datasources come from. A live export does know, when it exports the
+ * datasources too: they become `Datasource` declarations, and an
+ * `ExternalDatasource` with the same uid beside them fails the build (two
+ * datasources, one uid). A plain ref is what the importer itself writes when
+ * it cannot declare an external one (`settleExternals`), and GRAF101 still
+ * checks it against the declared `Datasource`.
+ */
+export function referDeclaredDatasources(plan: Plan, uids: ReadonlySet<string>): Plan {
+  const replaced = new Set<string>();
+  const declarations = plan.declarations.map((d): Declaration => {
+    if (d.kind !== "new" || d.className !== "ExternalDatasource") return d;
+    const { type, uid } = (d.props ?? {}) as { type?: unknown; uid?: unknown };
+    if (typeof type !== "string" || typeof uid !== "string" || !uids.has(uid)) return d;
+    replaced.add(d.id);
+    return {
+      id: d.id,
+      kind: "value",
+      value: { type, uid },
+      type: { text: `DatasourceRef<${JSON.stringify(type)}>`, imports: ["DatasourceRef"] },
+      name: d.name,
+      module: d.module,
+      comment: [`// Declared as a Datasource in datasources.ts, which this export also writes.`],
+    };
+  });
+  if (replaced.size === 0) return plan;
+  return { ...plan, declarations, exports: plan.exports.filter((id) => !replaced.has(id)) };
+}
+
+function logicalIdFor(text: string): string {
+  const w = text.split(/[^A-Za-z0-9]+/).filter((x) => x !== "");
+  const id = w.map((x, i) => (i === 0 ? x.charAt(0).toLowerCase() + x.slice(1) : x.charAt(0).toUpperCase() + x.slice(1))).join("");
+  return id === "" || /^[0-9]/.test(id) ? `dashboard${id.charAt(0).toUpperCase()}${id.slice(1)}` : id;
+}
+
+/**
+ * Live dashboards and datasources as import IR, for `chant import --from`.
+ *
+ * Each dashboard is planned by the importer exactly as a dashboard file
+ * would be, so the generated TypeScript is what `chant import` writes for
+ * the same JSON, except that a datasource exported alongside it is referred
+ * to by `{ type, uid }` (see `referDeclaredDatasources`). The datasources are
+ * planned as one provisioning file, with
+ * the secrets Grafana holds written as `[REDACTED]`: the generated source
+ * shows which secrets are set and must be filled in by hand (as
+ * `$__env{NAME}` references, which GRAF002 asks for).
+ */
+export function exportTemplate(input: {
+  dashboards: Array<{ json: Json; warnings?: string[] }>;
+  datasources: Json[];
+  keepDefaults?: boolean;
+}): TemplateIR {
+  const resources: ResourceIR[] = [];
+  const warnings: string[] = [];
+  const taken = new Set<string>();
+  const unique = (base: string): string => {
+    let id = base;
+    for (let n = 2; taken.has(id); n++) id = `${base}${n}`;
+    taken.add(id);
+    return id;
+  };
+
+  const exportedUids = new Set(input.datasources.map((ds) => ds.uid).filter((u): u is string => typeof u === "string"));
+  for (const d of input.dashboards) {
+    warnings.push(...(d.warnings ?? []));
+    const planned = planDashboard(d.json);
+    const { edits, warnings: planWarnings } = planned;
+    const plan = referDeclaredDatasources(planned.plan, exportedUids);
+    const title = typeof d.json.title === "string" && d.json.title !== "" ? d.json.title : String(d.json.uid ?? "dashboard");
+    const uid = typeof d.json.uid === "string" ? d.json.uid : title;
+    warnings.push(...planWarnings.map((w) => `dashboard ${uid}: ${w}`));
+    const metadata: DashboardResourceMetadata = { source: d.json, edits };
+    const properties: PlanResourceProperties = { plan };
+    resources.push({
+      logicalId: unique(logicalIdFor(title)),
+      type: DASHBOARD_RESOURCE_TYPE,
+      properties: properties as unknown as Json,
+      metadata: metadata as unknown as Json,
+    });
+  }
+
+  if (input.datasources.length > 0) {
+    const entries = input.datasources.map((ds) => datasourceProps(ds, { keepDefaults: input.keepDefaults }));
+    const redacted = entries.filter((e) => isObject(e.secureJsonData)).map((e) => `"${String(e.name)}"`);
+    if (redacted.length > 0) {
+      warnings.push(
+        `datasources: Grafana does not return secret values, so the secureJsonData of ${redacted.join(", ")} is written as [REDACTED]; ` +
+          "replace each with a $__env{NAME} or $__file{path} reference before building",
+      );
+    }
+    const { plan, warnings: dsWarnings } = planDatasourceProvisioning({ apiVersion: 1, datasources: entries });
+    warnings.push(...dsWarnings);
+    const properties: PlanResourceProperties = { plan };
+    resources.push({ logicalId: unique("datasources"), type: PROVISIONING_RESOURCE_TYPE, properties: properties as unknown as Json });
+  }
+
+  return { resources, parameters: [], warnings };
+}

package/src/import/mappings.ts

@@ -0,0 +1,264 @@
+/**
+ * What each piece of classic dashboard JSON becomes: the tables the
+ * importer's parser reads. They are the extension points for the issues
+ * that teach the importer more of Grafana.
+ *
+ * - Panel types (#2950): a built-in panel class is found in the panel
+ *   registry (`registeredPanels()`), so a class added with `builtin: true`
+ *   in `panels.ts` is used by the importer with no change here. Any other
+ *   type is declared in the imported source with `definePanel`.
+ * - Query types (#2951): the same, through `registeredQueries()`, keyed by
+ *   datasource plugin type; any other type gets a `defineQuery`.
+ * - Variable types (#2952): `VARIABLE_MAPPINGS` has one entry per type the
+ *   lexicon has a class for. A type with no entry (adhoc, groupby, switch)
+ *   is reported and left out. Add an entry when the class lands.
+ * - Dashboard and panel fields (#2953 annotations, and any new prop):
+ *   `DASHBOARD_FIELDS`, `PANEL_FIELDS` and `ROW_FIELDS` list the JSON keys
+ *   copied onto a prop as they are. A key in none of the tables, and not
+ *   handled by the parser, is reported and left out, unless it is at the
+ *   value Grafana assumes when it is missing (see `./normalize.ts`).
+ */
+
+import { registeredPanels, type PanelDefinition } from "../panels";
+import { registeredQueries, type QueryDefinition } from "../query";
+import type { VariableHide } from "../variables";
+import { splitValues } from "./normalize";
+
+type Json = Record<string, unknown>;
+
+/** Dashboard JSON keys carried onto the `Dashboard` prop of the same name, as they are. */
+export const DASHBOARD_FIELDS: readonly string[] = [
+  "title",
+  "uid",
+  "description",
+  "tags",
+  "time",
+  "refresh",
+  "timezone",
+  "weekStart",
+  "fiscalYearStartMonth",
+  "liveNow",
+  "timepicker",
+  "editable",
+  "links",
+];
+
+/** Panel JSON keys carried onto the panel prop of the same name, as they are. */
+export const PANEL_FIELDS: readonly string[] = [
+  "id",
+  "title",
+  "description",
+  "gridPos",
+  "options",
+  "fieldConfig",
+  "transformations",
+  "links",
+  "repeatDirection",
+  "maxPerRow",
+  "maxDataPoints",
+  "interval",
+  "timeFrom",
+  "timeShift",
+  "hideTimeOverride",
+  "transparent",
+  "pluginVersion",
+];
+
+/**
+ * Row JSON keys carried onto the `Row` prop of the same name. A row's
+ * `gridPos` is not among them: only its `y` is carried (Grafana draws a row
+ * header full width and one line high), so the row stays on its line even
+ * where the build would place it elsewhere, such as below an empty band.
+ */
+export const ROW_FIELDS: readonly string[] = ["id", "title", "collapsed"];
+
+/** `graphTooltip` as Grafana stores it, and as `Dashboard` takes it. */
+export const GRAPH_TOOLTIP: Readonly<Record<number, "default" | "sharedCrosshair" | "sharedTooltip">> = {
+  0: "default",
+  1: "sharedCrosshair",
+  2: "sharedTooltip",
+};
+
+/** A variable's `hide` as Grafana stores it, and as the variable classes take it. */
+export const VARIABLE_HIDE: Readonly<Record<number, VariableHide>> = { 0: "label", 1: "valueOnly", 2: "hidden" };
+
+/** A query variable's `refresh` as Grafana stores it, and as `QueryVariable` takes it. */
+export const QUERY_REFRESH: Readonly<Record<number, "never" | "onLoad" | "onTimeRangeChange">> = {
+  0: "never",
+  1: "onLoad",
+  2: "onTimeRangeChange",
+};
+
+/** The class a panel of this plugin type is declared with, when chant ships one. */
+export function builtinPanelFor(type: string): PanelDefinition | undefined {
+  return registeredPanels().find((d) => d.builtin && d.type === type);
+}
+
+/** The class a query to a datasource of this plugin type is declared with, when chant ships one. */
+export function builtinQueryFor(datasourceType: string): QueryDefinition | undefined {
+  return registeredQueries().find((d) => d.builtin && d.datasourceType === datasourceType);
+}
+
+/**
+ * The datasource type a query with no datasource of its own, on a panel
+ * with none, is declared under. Grafana sends it to the default datasource;
+ * the class exists only to hold the query model.
+ */
+export const DEFAULT_DATASOURCE_TYPE = "default";
+
+/** What converting one variable needs from the rest of the import. */
+export interface VariableContext {
+  /** The variable's JSON. */
+  readonly json: Json;
+  /** Its JSON pointer, for edits. */
+  readonly path: string;
+  /** Resolve a `datasource` value to a prop value, reporting what cannot be resolved. */
+  datasource(value: unknown, path: string): unknown;
+  /** Report a key that is not carried; `why` is the end of the sentence, after "not carried". */
+  drop(key: string, why?: string): void;
+  /** Report the whole variable as not carried. */
+  dropVariable(why: string): void;
+  /** Record that `key` is written differently but means the same, or with the given warning. */
+  replace(key: string, value: unknown, why?: string): void;
+}
+
+/** One variable type the lexicon has a class for: which class, and how its JSON becomes props. */
+export interface VariableMapping {
+  readonly className: string;
+  /** JSON keys the mapping reads, whether it carries them or derives them. Any other key is reported. */
+  readonly keys: readonly string[];
+  /** The type-specific props, or undefined when the variable cannot be carried (after `ctx.dropVariable`). */
+  convert(ctx: VariableContext): Json | undefined;
+}
+
+function str(v: unknown): string | undefined {
+  return typeof v === "string" ? v : undefined;
+}
+
+function nonEmpty(v: unknown): boolean {
+  if (v === undefined || v === null || v === "" || v === false) return false;
+  if (Array.isArray(v)) return v.length > 0;
+  if (typeof v === "object") return Object.keys(v as object).length > 0;
+  return true;
+}
+
+/** Split a custom or interval variable's `query` the way Grafana does: on commas not escaped as `\\,`, trimmed. */
+export const valuesOf = splitValues;
+
+function multiValue(json: Json): Json {
+  const out: Json = {};
+  if (json.multi === true) out.multi = true;
+  if (json.includeAll === true) out.includeAll = true;
+  if (nonEmpty(json.allValue)) out.allValue = json.allValue;
+  return out;
+}
+
+function current(json: Json): Json {
+  return nonEmpty(json.current) ? { current: json.current } : {};
+}
+
+const MULTI_KEYS = ["multi", "includeAll", "allValue"];
+
+/** Per Grafana variable type, the class and props it becomes. */
+export const VARIABLE_MAPPINGS: Readonly<Record<string, VariableMapping>> = {
+  query: {
+    className: "QueryVariable",
+    keys: ["datasource", "query", "definition", "regex", "refresh", "sort", "options", "current", ...MULTI_KEYS],
+    convert(ctx) {
+      const { json } = ctx;
+      let query = str(json.query);
+      if (query === undefined && json.query !== null && typeof json.query === "object") {
+        const obj = json.query as Json;
+        query = str(obj.query);
+        if (query === undefined) {
+          ctx.dropVariable("its query is an object with no query string, which QueryVariable cannot hold yet (#2952)");
+          return undefined;
+        }
+        // refId is the editor's own id for the query, which Grafana gives the string form back.
+        const rest = Object.keys(obj).filter((k) => k !== "query" && k !== "refId");
+        ctx.replace(
+          "query",
+          query,
+          rest.length === 0 ? undefined : `is an object; it is written as its query string, and its ${rest.join(" and ")} ${rest.length === 1 ? "is" : "are"} not carried (#2952)`,
+        );
+      }
+      query ??= "";
+      if (nonEmpty(json.definition) && json.definition !== query) ctx.drop("definition", `(it differs from the query, which is kept)`);
+      const refresh = typeof json.refresh === "number" ? json.refresh : 1;
+      if (refresh === 0 && nonEmpty(json.options)) {
+        ctx.drop("options", "(QueryVariable does not store options; with refresh never, Grafana shows none until it is refreshed)");
+      }
+      const out: Json = { datasource: ctx.datasource(json.datasource, `${ctx.path}/datasource`), query };
+      if (out.datasource === undefined) {
+        ctx.dropVariable("it has no datasource chant can refer to, and QueryVariable needs one");
+        return undefined;
+      }
+      if (nonEmpty(json.regex)) out.regex = json.regex;
+      if (refresh !== 1 && QUERY_REFRESH[refresh]) out.refresh = QUERY_REFRESH[refresh];
+      if (typeof json.sort === "number" && json.sort !== 0) out.sort = json.sort;
+      return { ...out, ...multiValue(json), ...current(json) };
+    },
+  },
+  custom: {
+    className: "CustomVariable",
+    keys: ["query", "options", "current", ...MULTI_KEYS],
+    convert(ctx) {
+      const { json } = ctx;
+      return { values: valuesOf(str(json.query) ?? ""), ...multiValue(json), ...current(json) };
+    },
+  },
+  interval: {
+    className: "IntervalVariable",
+    keys: ["query", "options", "current", "refresh", "auto", "auto_count", "auto_min"],
+    convert(ctx) {
+      const { json } = ctx;
+      const out: Json = { values: valuesOf(str(json.query) ?? "") };
+      if (json.auto === true) out.auto = true;
+      if (typeof json.auto_count === "number" && json.auto_count !== 30) out.autoCount = json.auto_count;
+      if (typeof json.auto_min === "string" && json.auto_min !== "10s") out.autoMin = json.auto_min;
+      return { ...out, ...current(json) };
+    },
+  },
+  datasource: {
+    className: "DatasourceVariable",
+    keys: ["query", "regex", "refresh", "options", "current", ...MULTI_KEYS],
+    convert(ctx) {
+      const { json } = ctx;
+      const pluginType = str(json.query);
+      if (!pluginType) {
+        ctx.dropVariable("it names no datasource plugin type");
+        return undefined;
+      }
+      const out: Json = { pluginType };
+      if (nonEmpty(json.regex)) out.regex = json.regex;
+      return { ...out, ...multiValue(json), ...current(json) };
+    },
+  },
+  constant: {
+    className: "ConstantVariable",
+    keys: ["query", "options", "current", "hide"],
+    convert(ctx) {
+      const { json } = ctx;
+      if (json.hide !== undefined && json.hide !== 2) {
+        ctx.replace("hide", 2, "is not 2: chant always writes a constant hidden, as Grafana shows it");
+      }
+      return { value: str(json.query) ?? "" };
+    },
+  },
+  textbox: {
+    className: "TextboxVariable",
+    keys: ["query", "options", "current"],
+    convert(ctx) {
+      const { json } = ctx;
+      const value = str(json.query) ?? "";
+      const cur = json.current as Json | undefined;
+      if (nonEmpty(cur) && cur!.value !== value) {
+        ctx.drop("current", `(the box's value "${String(cur!.value)}"; TextboxVariable starts at its default, "${value}")`);
+      }
+      return value === "" ? {} : { value };
+    },
+  },
+};
+
+/** Keys every variable type reads: the ones `CommonVariableProps` has, and `type`. */
+export const COMMON_VARIABLE_KEYS: readonly string[] = ["type", "name", "label", "description", "hide", "skipUrlSync"];

package/src/import/model.ts

@@ -0,0 +1,110 @@
+/**
+ * The plan `chant import` hands from the parser to the generator: the
+ * declarations one dashboard becomes, with the references between them.
+ *
+ * The parser decides what each piece of dashboard JSON becomes (which
+ * class, which props, what cannot be carried) using the tables in
+ * `./mappings.ts`. The generator decides only how the plan is written:
+ * names, modules, imports, lifted consts. It knows nothing about Grafana,
+ * so live export (#2946) can build a plan from a dashboard read over the
+ * API and write it with the same generator.
+ */
+
+/** A value in a declaration's props that refers to another declaration, written as that declaration's variable. */
+export interface DeclRef {
+  readonly $decl: string;
+}
+
+export function declRef(id: string): DeclRef {
+  return { $decl: id };
+}
+
+export function isDeclRef(v: unknown): v is DeclRef {
+  return typeof v === "object" && v !== null && typeof (v as DeclRef).$decl === "string" && Object.keys(v).length === 1;
+}
+
+/**
+ * A value written as a call to a function the package exports, e.g.
+ * `customTransformation("sortBy", { ... })` for a transformation the typed
+ * form can't hold. The arguments are values like any other.
+ */
+export interface CallValue {
+  readonly $call: string;
+  readonly args: readonly unknown[];
+}
+
+export function callValue(fn: string, args: readonly unknown[]): CallValue {
+  return { $call: fn, args };
+}
+
+export function isCallValue(v: unknown): v is CallValue {
+  return typeof v === "object" && v !== null && typeof (v as CallValue).$call === "string" && Array.isArray((v as CallValue).args) && Object.keys(v).length === 2;
+}
+
+/** Where a declaration's variable name comes from: a text to camelCase, or another declaration's name plus a suffix. */
+export type NameHint = string | { readonly of: string; readonly suffix: string };
+
+/**
+ * One declaration.
+ *
+ * - `new`: `const name = new ClassName(props);`, a declarable.
+ * - `value`: `const name: type = value;`, a plain value other declarations
+ *   refer to (a `DatasourceRef`).
+ */
+export interface Declaration {
+  /** Unique in the plan, e.g. `panel:4`, `query:4:A`, `variable:job`, `datasource:prometheus:prom`, `dashboard`. */
+  readonly id: string;
+  readonly kind: "new" | "value";
+  /** For `new`: the class. A package export unless `customClass` says the import declares it. */
+  readonly className?: string;
+  /** For `new`: the id of the `CustomClass` declaring `className`, when it is not a package export. */
+  readonly customClass?: string;
+  /** For `new`: the constructor's props, in source order. */
+  readonly props?: Record<string, unknown>;
+  /** For `value`: the value, and its type annotation with the package types it names. */
+  readonly value?: unknown;
+  readonly type?: { readonly text: string; readonly imports: readonly string[] };
+  readonly name: NameHint;
+  /** The module group it is written to (see `Plan.modules`). */
+  readonly module: string;
+  /**
+   * Declarations with the same unit stay in the same file when a module is
+   * split (a panel and its queries). Defaults to the id.
+   */
+  readonly unit?: string;
+  /** Comment lines written above it. */
+  readonly comment?: readonly string[];
+}
+
+/** A panel or query class the import declares, for a plugin chant has no class for. */
+export interface CustomClass {
+  /** e.g. `panel-class:grafana-clock-panel`, `query-class:elasticsearch`. */
+  readonly id: string;
+  readonly className: string;
+  /** `definePanel` or `defineQuery`. */
+  readonly factory: "definePanel" | "defineQuery";
+  /** The definition object passed to the factory. */
+  readonly definition: Record<string, unknown>;
+  readonly comment: readonly string[];
+}
+
+/** One module group: a base file name and the doc comment at its top. */
+export interface ModuleSpec {
+  readonly key: string;
+  /** File name without `.ts`; `-1`, `-2`, ... is added when the group is split. */
+  readonly file: string;
+  readonly summary: string;
+}
+
+/** Everything one dashboard becomes. */
+export interface Plan {
+  /** The directory its modules are written to, relative to the output directory. `""` for none. */
+  readonly directory: string;
+  /** Modules in the order they are written. */
+  readonly modules: readonly ModuleSpec[];
+  /** Declarations in dependency order: a declaration only refers to ones before it. */
+  readonly declarations: readonly Declaration[];
+  readonly customClasses: readonly CustomClass[];
+  /** Declarations exported even when no other module imports them (the dashboard). */
+  readonly exports: readonly string[];
+}