@intentius/chant-lexicon-grafana 0.98.0 → 0.100.0

package/src/import.e2e.test.ts

@@ -1,24 +1,22 @@
 /**
  * "A dashboard builds to JSON that Grafana imports without edits", against
- * Grafana itself.
+ * Grafana itself, on every release in `GRAFANA_IMAGES` (12.4 and 13.2).
  *
  * Builds each example (getting-started, and dashboards-from-declarations,
  * whose dashboards the RED, SLO and agent composites build), mounts its
  * provisioning files and dashboards into a pinned `grafana/grafana`
- * container, and asserts that
- * Grafana provisioned every datasource and dashboard and hands each
- * dashboard back with the panels that were built. It then imports the same
- * JSON a second time through `POST /api/dashboards/db`, the path the UI's
- * import uses, under another uid.
+ * container, and asserts that Grafana provisioned every datasource and
+ * dashboard, and that each stored dashboard model is the built JSON, key
+ * for key, once the keys Grafana adds (`GRAFANA_INJECTED`: `id` and
+ * `version`) are taken out. It then imports the same JSON a second time
+ * through `POST /api/dashboards/db`, the path the UI's import uses, under
+ * another uid, and compares that stored model the same way.
  *
  * Skipped, with the reason in the test name, when Docker is not running.
- * On demand: `npx vitest run --project e2e lexicons/grafana`.
+ * On demand: `npx vitest run --project e2e lexicons/grafana/src/import.e2e.test.ts`.
  */
-import { execSync } from "node:child_process";
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
+import { mkdirSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
 import { afterAll, describe, expect, it } from "vitest";
 import { build } from "@intentius/chant/build";
 import type { SerializerResult } from "@intentius/chant/serializer";
@@ -26,23 +24,12 @@ import type { Serializer } from "@intentius/chant/serializer";
 import { otelSerializer } from "@intentius/chant-lexicon-otel/serializer";
 import { prometheusSerializer } from "@intentius/chant-lexicon-prometheus/serializer";
 import { grafanaSerializer } from "./serializer";
+import { DockerScope, GRAFANA_IMAGES, dockerAvailable, waitFor } from "../test/e2e/containers";
+import { withoutInjected } from "../test/e2e/stored-model";
 
-/** The Grafana release the import test runs against; `CHANT_GRAFANA_IMAGE` overrides it. */
-export const GRAFANA_IMAGE = process.env.CHANT_GRAFANA_IMAGE ?? "grafana/grafana:12.4.11";
-
-function available(cmd: string): boolean {
-  try {
-    execSync(cmd, { stdio: "ignore" });
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-const hasDocker = available("docker info");
+const hasDocker = dockerAvailable();
 const skipReason = hasDocker ? "" : "Docker is not running";
-const AUTH = `Basic ${Buffer.from("admin:admin").toString("base64")}`;
-const examples = join(dirname(dirname(fileURLToPath(import.meta.url))), "examples");
+const examples = join(import.meta.dirname, "..", "examples");
 
 /** Each example, and the serializers its build root needs. */
 const EXAMPLES: Array<{ name: string; serializers: Serializer[] }> = [
@@ -50,98 +37,58 @@ const EXAMPLES: Array<{ name: string; serializers: Serializer[] }> = [
   { name: "dashboards-from-declarations", serializers: [otelSerializer, prometheusSerializer, grafanaSerializer] },
 ];
 
-async function waitFor<T>(what: string, fn: () => Promise<T | undefined>, timeoutMs = 120_000): Promise<T> {
-  const deadline = Date.now() + timeoutMs;
-  let last: unknown;
-  while (Date.now() < deadline) {
-    try {
-      const v = await fn();
-      if (v !== undefined) return v;
-    } catch (err) {
-      last = err;
-    }
-    await new Promise((r) => setTimeout(r, 1000));
-  }
-  throw new Error(`timed out waiting for ${what}${last ? `: ${String(last)}` : ""}`);
-}
+const MATRIX = GRAFANA_IMAGES.flatMap((image) => EXAMPLES.map((e) => ({ ...e, image })));
 
-describe.skipIf(!hasDocker).each(EXAMPLES)(`Grafana imports the $name dashboards without edits${skipReason ? ` (skipped: ${skipReason})` : ""}`, ({ name, serializers }) => {
-  const CONTAINER = `chant-grafana-import-${name}-${process.pid}`;
-  const dir = mkdtempSync(join(tmpdir(), "chant-grafana-import-"));
+describe.skipIf(!hasDocker).each(MATRIX)(`$image imports the $name dashboards without edits${skipReason ? ` (skipped: ${skipReason})` : ""}`, ({ name, serializers, image }) => {
+  const scope = new DockerScope(`grafana-import-${name}`);
 
-  afterAll(() => {
-    try {
-      execSync(`docker rm -f ${CONTAINER}`, { stdio: "ignore" });
-    } catch {
-      // already gone
-    }
-    rmSync(dir, { recursive: true, force: true });
-  });
+  afterAll(() => scope.cleanup());
 
-  it("provisions every datasource and dashboard, and accepts the JSON through the import API", { timeout: 300_000 }, async () => {
+  it("provisions every datasource and dashboard as built, and accepts the JSON through the import API", { timeout: 300_000 }, async () => {
     const result = await build(join(examples, name, "src"), serializers);
     expect(result.errors).toEqual([]);
     const out = result.outputs.get("grafana") as SerializerResult;
+    const dir = scope.tempDir();
     for (const [file, content] of Object.entries(out.files ?? {})) {
       mkdirSync(dirname(join(dir, file)), { recursive: true });
       writeFileSync(join(dir, file), content);
     }
     const index = JSON.parse(out.primary) as { dashboards: Array<{ uid: string; title: string; folder?: string; file: string }>; datasources: Array<{ uid: string; type: string; name: string }> };
 
-    execSync(
-      [
-        "docker run -d",
-        `--name ${CONTAINER}`,
-        "-p 127.0.0.1::3000",
-        "-e GF_SECURITY_ADMIN_PASSWORD=admin",
-        "-e GF_ANALYTICS_REPORTING_ENABLED=false",
-        "-e GF_ANALYTICS_CHECK_FOR_UPDATES=false",
-        `-v ${join(dir, "provisioning")}:/etc/grafana/provisioning:ro`,
-        `-v ${join(dir, "dashboards")}:/var/lib/grafana/dashboards:ro`,
-        GRAFANA_IMAGE,
-      ].join(" "),
-      { stdio: "ignore" },
-    );
-    const port = execSync(`docker port ${CONTAINER} 3000/tcp`).toString().trim().split("\n")[0].split(":").pop();
-    const base = `http://127.0.0.1:${port}`;
-    const api = async (path: string, init?: RequestInit) => {
-      const res = await fetch(`${base}${path}`, { ...init, headers: { authorization: AUTH, "content-type": "application/json", ...(init?.headers ?? {}) } });
-      return { status: res.status, body: (await res.json()) as Record<string, unknown> & unknown[] };
-    };
-
-    await waitFor("Grafana to answer", async () => ((await fetch(`${base}/api/health`)).ok ? true : undefined));
+    const grafana = await scope.grafana({ image, provisioningDir: join(dir, "provisioning"), dashboardsDir: join(dir, "dashboards") });
+    const { api } = grafana;
 
     // Datasources: every declared one, with the uid and type chant gave it.
     const datasources = await waitFor("datasources", async () => {
       const { status, body } = await api("/api/datasources");
-      return status === 200 && (body as unknown[]).length >= index.datasources.length ? (body as unknown as Array<{ uid: string; type: string; name: string }>) : undefined;
+      return status === 200 && (body as unknown[]).length >= index.datasources.length ? (body as Array<{ uid: string; type: string; name: string }>) : undefined;
     });
     expect(datasources.map((d) => [d.uid, d.type, d.name]).sort()).toEqual(index.datasources.map((d) => [d.uid, d.type, d.name]).sort());
 
-    // Dashboards: provisioned, in their folder, with every panel as built.
+    // Dashboards: provisioned, in their folder, and stored exactly as built.
     for (const d of index.dashboards) {
       const { body } = await waitFor(`dashboard ${d.uid}`, async () => {
         const r = await api(`/api/dashboards/uid/${d.uid}`);
         return r.status === 200 ? r : undefined;
       });
       const meta = body.meta as { provisioned: boolean; folderTitle?: string };
-      const stored = body.dashboard as { title: string; panels: Array<Record<string, unknown>>; templating: { list: unknown[] } };
-      const built = JSON.parse(out.files![d.file]) as typeof stored;
+      const stored = body.dashboard as Record<string, unknown>;
+      const built = JSON.parse(out.files![d.file]) as Record<string, unknown>;
       expect(meta.provisioned).toBe(true);
       if (d.folder) expect(meta.folderTitle).toBe(d.folder);
-      expect(stored.title).toBe(d.title);
-      const shape = (panels: Array<Record<string, unknown>>) => panels.map((p) => [p.id, p.type, p.title, p.gridPos]);
-      expect(shape(stored.panels)).toEqual(shape(built.panels));
-      expect(stored.templating.list.length).toBe(built.templating.list.length);
+      expect(typeof stored.id, `${d.uid}: Grafana assigns the id`).toBe("number");
+      expect(stored.version, `${d.uid}: Grafana's first version`).toBe(1);
+      expect(withoutInjected(stored), `${image} stored ${d.uid} differently from the build`).toStrictEqual(built);
     }
 
     // The same JSON through the import API, under a new uid.
     const first = index.dashboards[0];
-    const copy = { ...JSON.parse(out.files![first.file]), uid: `${first.uid}-api`, title: `${first.title} (API import)` };
+    const copy = { ...(JSON.parse(out.files![first.file]) as Record<string, unknown>), uid: `${first.uid}-api`, title: `${first.title} (API import)` };
     const imported = await api("/api/dashboards/db", { method: "POST", body: JSON.stringify({ dashboard: copy, overwrite: false }) });
     expect(imported.status).toBe(200);
     expect(imported.body.status).toBe("success");
     const back = await api(`/api/dashboards/uid/${first.uid}-api`);
-    expect((back.body.dashboard as { panels: unknown[] }).panels.length).toBe(copy.panels.length);
+    expect(back.status).toBe(200);
+    expect(withoutInjected(back.body.dashboard as Record<string, unknown>), `${image} stored the API import differently from the JSON sent`).toStrictEqual(copy);
   });
 });

package/src/import.test.ts

@@ -3,7 +3,7 @@
  *
  * Builds every example and validates each dashboard against Grafana's
  * dashboard schema at `GRAFANA_SCHEMA_PIN`, each panel's options and each
- * query against their plugin's schema, and runs GRAF101-GRAF107 over the
+ * query against their plugin's schema, and runs the GRAF1xx checks over the
  * output. `import.e2e.test.ts` does the same against a real Grafana when
  * Docker is available.
  */
@@ -18,6 +18,7 @@ import { grafanaSerializer } from "./serializer";
 import { validateDashboardSchema } from "./schema-validate";
 import { validateGrafanaOutput } from "./validate-output";
 import type { ProvisionedDatasource } from "./build";
+import { ALERTING_FILE } from "./alerting-build";
 
 const examplesDir = join(dirname(dirname(fileURLToPath(import.meta.url))), "examples");
 const examples = readdirSync(examplesDir).filter((e) => {
@@ -34,12 +35,17 @@ describe.each(examples)("example %s", (example) => {
     expect(result.errors).toEqual([]);
     const out = result.outputs.get("grafana") as SerializerResult;
     const dashboards = Object.entries(out.files ?? {}).filter(([f]) => f.startsWith("dashboards/"));
-    expect(dashboards.length).toBeGreaterThan(0);
+    const alerting = out.files?.[ALERTING_FILE];
+    expect(dashboards.length + (alerting ? 1 : 0)).toBeGreaterThan(0);
     for (const [file, text] of dashboards) {
       expect({ file, problems: validateDashboardSchema(JSON.parse(text)) }).toEqual({ file, problems: [] });
     }
     const ds = load(out.files?.["provisioning/datasources/chant.yaml"] ?? "datasources: []") as { datasources: ProvisionedDatasource[] };
-    const issues = validateGrafanaOutput({ dashboards: dashboards.map(([source, t]) => ({ source, json: JSON.parse(t) })), datasources: ds.datasources });
+    const issues = validateGrafanaOutput({
+      dashboards: dashboards.map(([source, t]) => ({ source, json: JSON.parse(t) })),
+      datasources: ds.datasources,
+      alerting: alerting ? [{ source: ALERTING_FILE, json: load(alerting) as Record<string, unknown> }] : [],
+    });
     expect(issues).toEqual([]);
   });
 });

package/src/index.ts

@@ -8,8 +8,21 @@ export { grafanaSerializer } from "./serializer";
 export {
   Datasource,
   DATASOURCE_TYPE,
+  ExternalDatasource,
+  EXTERNAL_DATASOURCE_TYPE,
   BUILTIN_DATASOURCE_UIDS,
   isDatasourceEntity,
+  isExternalDatasource,
+  isDatasourceDeclaration,
+  DatasourceProvisioning,
+  DATASOURCE_PROVISIONING_TYPE,
+  isDatasourceProvisioningEntity,
+  type DatasourceProvisioningProps,
+  type DatasourceProvisioningEntity,
+  type DeletedDatasource,
+  type ExternalDatasourceProps,
+  type ExternalDatasourceEntity,
+  type ExternalDatasourceConstructor,
   type DatasourceProps,
   type DatasourceEntity,
   type DatasourceConstructor,
@@ -18,6 +31,64 @@ export {
   type KnownDatasourceType,
 } from "./datasource";
 
+// Typed datasource settings (jsonData, secureJsonData keys) per plugin
+export {
+  JSONDATA_LINKS,
+  TRACING_DATASOURCE_TYPES,
+  TRACE_TO_LOGS_DATASOURCE_TYPES,
+  TRACE_TO_METRICS_DATASOURCE_TYPES,
+  type JsonDataLink,
+  type LinkedDatasource,
+  type TracingDatasourceType,
+  type TraceToLogsDatasourceType,
+  type TraceToMetricsDatasourceType,
+  type TypedDatasourceType,
+  type DatasourceJsonData,
+  type DatasourceSecureJsonData,
+  type DatasourceJsonDataTypes,
+  type DatasourceSecureJsonKeys,
+  type CommonJsonData,
+  type HttpJsonData,
+  type HttpSecureJsonKey,
+  type PrometheusJsonData,
+  type ExemplarTraceIdDestination,
+  type LokiJsonData,
+  type DerivedFieldConfig,
+  type TempoJsonData,
+  type TraceToLogsTag,
+  type TraceToLogsOptions,
+  type TraceToLogsOptionsV2,
+  type TraceToMetricsOptions,
+  type TraceToProfilesOptions,
+  type ElasticsearchJsonData,
+  type ElasticsearchDataLink,
+  type ElasticsearchSecureJsonKey,
+  type AwsAuthJsonData,
+  type AwsAuthSecureJsonKey,
+  type CloudWatchJsonData,
+  type CloudWatchLogGroup,
+  type CloudWatchSecureJsonKey,
+  type AzureCloudName,
+  type AzureCredentials,
+  type AzureMonitorJsonData,
+  type AzureMonitorSecureJsonKey,
+  type GoogleAuthJsonData,
+  type GoogleAuthSecureJsonKey,
+  type CloudMonitoringJsonData,
+  type CloudMonitoringSecureJsonKey,
+  type BigQueryJsonData,
+  type BigQuerySecureJsonKey,
+  type PyroscopeJsonData,
+  type PyroscopeSecureJsonKey,
+  type SqlJsonData,
+  type PostgresJsonData,
+  type PostgresSecureJsonKey,
+  type MySQLJsonData,
+  type MySQLSecureJsonKey,
+  type MSSQLJsonData,
+  type MSSQLSecureJsonKey,
+} from "./datasource-settings";
+
 // Dashboards and provisioning
 export {
   Dashboard,
@@ -32,8 +103,106 @@ export {
   type DashboardLinkInput,
   type DashboardProviderProps,
   type DashboardProviderEntity,
+  type DashboardEntityProps,
+  type DashboardProviderEntityProps,
 } from "./dashboard";
 
+// Folders and annotations
+export { Folder, FOLDER_TYPE, isFolderEntity, folderLevels, type FolderProps, type FolderEntity } from "./folder";
+export { annotationJson, ANNOTATION_REF_ID, type AnnotationInput } from "./annotations";
+
+// Grafana-managed alerting
+export {
+  AlertRuleGroup,
+  AlertRule,
+  AlertQuery,
+  ReduceExpression,
+  MathExpression,
+  ThresholdExpression,
+  ResampleExpression,
+  ClassicConditionsExpression,
+  SqlExpression,
+  ContactPoint,
+  NotificationPolicy,
+  MuteTiming,
+  NotificationTemplate,
+  ALERT_RULE_GROUP_TYPE,
+  ALERT_RULE_TYPE,
+  ALERT_QUERY_TYPE,
+  EXPRESSION_TYPE_PREFIX,
+  EXPRESSION_DATASOURCE_UID,
+  CONTACT_POINT_TYPE,
+  NOTIFICATION_POLICY_TYPE,
+  MUTE_TIMING_TYPE,
+  NOTIFICATION_TEMPLATE_TYPE,
+  isAlertRuleGroupEntity,
+  isAlertRuleEntity,
+  isAlertQueryEntity,
+  isExpressionEntity,
+  isContactPointEntity,
+  isNotificationPolicyEntity,
+  isMuteTimingEntity,
+  isNotificationTemplateEntity,
+  type AlertRuleGroupProps,
+  type AlertRuleGroupEntity,
+  type AlertRuleProps,
+  type AlertRuleEntity,
+  type AlertRuleData,
+  type AlertRuleNotificationSettings,
+  type AlertRuleRecord,
+  type AlertQueryProps,
+  type AlertQueryEntity,
+  type AlertDuration,
+  type RelativeTimeRange,
+  type ExpressionEntity,
+  type ExpressionKind,
+  type ReduceExpressionProps,
+  type MathExpressionProps,
+  type ThresholdExpressionProps,
+  type ResampleExpressionProps,
+  type ClassicConditionsExpressionProps,
+  type SqlExpressionProps,
+  type NoDataState,
+  type ExecErrState,
+  type ContactPointProps,
+  type ContactPointEntity,
+  type ContactPointReceiver,
+  type ContactPointIntegrationType,
+  type NotificationPolicyProps,
+  type NotificationPolicyEntity,
+  type PolicyRoute,
+  type ObjectMatcher,
+  type MuteTimingProps,
+  type MuteTimingEntity,
+  type NotificationTemplateProps,
+  type NotificationTemplateEntity,
+} from "./alerting";
+export {
+  buildAlerting,
+  alertingYaml,
+  alertRuleJson,
+  alertQueryJson,
+  ruleGroupJson,
+  contactPointJson,
+  notificationPolicyJson,
+  muteTimingJson,
+  notificationTemplateJson,
+  durationSeconds,
+  ALERTING_FILE,
+  ALERTING_FILE_KEYS,
+  DEFAULT_RELATIVE_TIME_RANGE,
+  DEFAULT_GROUP_INTERVAL,
+  type AlertingFile,
+  type AlertingIndex,
+  type ProvisionedRuleGroup,
+  type ProvisionedAlertRule,
+  type ProvisionedAlertQuery,
+  type ProvisionedContactPoint,
+  type ProvisionedMuteTiming,
+  type ProvisionedTemplate,
+} from "./alerting-build";
+export { CONTACT_POINT_SECRET_SETTINGS } from "./contact-point-secrets";
+
 // Panels and rows, and the extension point for other panel plugins
 export {
   TimeSeriesPanel,
@@ -44,6 +213,19 @@ export {
   TracesPanel,
   HeatmapPanel,
   TextPanel,
+  BarChartPanel,
+  BarGaugePanel,
+  PieChartPanel,
+  StateTimelinePanel,
+  StatusHistoryPanel,
+  HistogramPanel,
+  NodeGraphPanel,
+  XYChartPanel,
+  TrendPanel,
+  CanvasPanel,
+  GeomapPanel,
+  FlameGraphPanel,
+  AlertListPanel,
   Row,
   definePanel,
   registeredPanels,
@@ -67,6 +249,15 @@ export {
   PromQuery,
   TempoQuery,
   LokiQuery,
+  ElasticsearchQuery,
+  CloudWatchQuery,
+  AzureMonitorQuery,
+  CloudMonitoringQuery,
+  BigQueryQuery,
+  PyroscopeQuery,
+  PostgresQuery,
+  MySQLQuery,
+  MSSQLQuery,
   defineQuery,
   registeredQueries,
   queryDefinitionFor,
@@ -74,6 +265,8 @@ export {
   QUERY_TYPE_PREFIX,
   type DatasourceInput,
   type QueryModel,
+  type Loosen,
+  type MergedModel,
   type QueryProps,
   type QueryDefinition,
   type QueryEntity,
@@ -81,8 +274,30 @@ export {
   type PromQueryEntity,
   type TempoQueryEntity,
   type LokiQueryEntity,
+  type ElasticsearchQueryEntity,
+  type CloudWatchQueryEntity,
+  type AzureMonitorQueryEntity,
+  type CloudMonitoringQueryEntity,
+  type BigQueryQueryEntity,
+  type PyroscopeQueryEntity,
+  type PostgresQueryEntity,
+  type MySQLQueryEntity,
+  type MSSQLQueryEntity,
 } from "./query";
 
+// Hand-written query models for datasources with no schema
+export type {
+  SqlQueryModel,
+  SqlBuilderQuery,
+  SqlQueryFormat,
+  SqlExpressionType,
+  SqlProperty,
+  SqlFunctionExpression,
+  SqlFunctionParameterExpression,
+  SqlGroupByExpression,
+  SqlPropertyExpression,
+} from "./query-models";
+
 // Variables
 export {
   QueryVariable,
@@ -107,14 +322,50 @@ export {
   type DatasourceVariableProps,
   type ConstantVariableProps,
   type TextboxVariableProps,
+  AdhocVariable,
+  GroupByVariable,
+  SwitchVariable,
+  MULTI_VALUE_KINDS,
+  type AdhocVariableProps,
+  type GroupByVariableProps,
+  type SwitchVariableProps,
+  type AdhocFilter,
+  type VariableKeyOption,
+  type VariableQueryObject,
+  type PrometheusVariableQuery,
 } from "./variables";
 
 // The generated schema types and their pin
 export * as schema from "./schema";
 export { DASHBOARD_SCHEMA_VERSION } from "./schema";
-export { GRAFANA_SCHEMA_PIN, SCHEMA_NAMES, type GrafanaSchemaPin, type SchemaName } from "./pin";
+export {
+  GRAFANA_SCHEMA_PIN,
+  SCHEMA_NAMES,
+  IMPORT_ONLY_SCHEMA_NAMES,
+  VENDORED_SCHEMA_NAMES,
+  type GrafanaSchemaPin,
+  type SchemaName,
+  type ImportOnlySchemaName,
+  type VendoredSchemaName,
+} from "./pin";
+// Hand-written options for the built-in panels with no schema
+export type { AlertListOptions, AlertListSortOrder, AlertListStateFilter, FlameGraphOptions } from "./panel-options";
 
-// Plain-data API: render, check and detect without a build
+// Panel transformations, typed per transformer (Grafana v13.2.2)
+export {
+  transformation,
+  customTransformation,
+  TRANSFORMATION_IDS,
+  type Transformation,
+  type KnownTransformation,
+  type CustomTransformation,
+  type TransformationCommon,
+  type TransformationId,
+  type TransformationOptionsById,
+  type ReducerId,
+} from "./transformations";
+
+// Plain-data API: render and detect without a build
 export {
   buildGrafana,
   grafanaFiles,
@@ -124,10 +375,13 @@ export {
   panelsJson,
   targetJson,
   variableModel,
+  customVariableOptions,
   datasourceRef,
   provisionedDatasource,
+  externalDatasourceRecord,
   provisionedProvider,
   datasourcesYaml,
+  datasourceFileSettings,
   dashboardProvidersYaml,
   GRID_COLUMNS,
   DATASOURCES_FILE,
@@ -137,30 +391,36 @@ export {
   type BuiltDashboard,
   type GrafanaIndex,
   type ProvisionedDatasource,
+  type ExternalDatasourceRecord,
   type ProvisionedProvider,
+  type DatasourceFileSettings,
   type DashboardJson,
   type PanelJson,
   type RowPanelJson,
   type VariableModel,
   type DataSourceRef,
 } from "./build";
+// The checks as plain functions (validateGrafanaOutput, validateDashboardSchema)
+// are on the `@intentius/chant-lexicon-grafana/validation` subpath (#2958), so
+// declaring dashboards does not load them.
 export {
-  validateGrafanaOutput,
-  issuesFor,
+  datasourceUses,
   variableReferences,
-  type GrafanaIssue,
-  type GrafanaIssueCode,
-  type GrafanaArtifacts,
-  type DashboardDoc,
-} from "./validate-output";
-export { validateDashboardSchema, type SchemaProblem } from "./schema-validate";
-export { looksLikeDashboard, looksLikeDatasourceProvisioning, looksLikeDashboardProvisioning } from "./detect";
-export { slugUid, isValidUid, UID_PATTERN, type DeepPartial } from "./util";
-
-// Composites: dashboards built from a spanmetrics connector, an Slo and the GenAI preset
+  resolveDatasourceRef,
+  knownDatasources,
+  type DatasourceUse,
+  type ResolvedDatasource,
+  type KnownDatasource,
+  type DatasourceRefJson,
+} from "./datasource-refs";
+export { looksLikeDashboard, looksLikeDatasourceProvisioning, looksLikeDashboardProvisioning, looksLikeAlertingProvisioning } from "./detect";
+export { slugUid, isValidUid, UID_PATTERN, type DeepPartial, type PropsOf } from "./util";
+
+// Composites: dashboards built from a spanmetrics connector, an Slo and the GenAI preset, and an Slo's burn-rate alerts as Grafana rules
 export {
   RedDashboard,
   redQueries,
+  RED_DEFAULT_SPAN_KINDS,
   SloDashboard,
   sloQueries,
   AgentDashboard,
@@ -168,6 +428,7 @@ export {
   type RedDashboardProps,
   type RedDashboardMembers,
   type RedDashboardInstance,
+  type SpanKind,
   type SloDashboardProps,
   type SloDashboardMembers,
   type SloDashboardInstance,
@@ -175,4 +436,37 @@ export {
   type AgentDashboardMembers,
   type AgentDashboardInstance,
   type DashboardOptions,
+  SloAlertRules,
+  sloAlertQueries,
+  type SloAlertRulesProps,
+  type SloAlertRulesMembers,
+  type SloAlertRulesInstance,
 } from "./composites";
+
+// Config namespace (#2946): `grafana.profiles.<env>` in chant.config.ts, the
+// Grafana each environment is observed in and exported from.
+export { grafanaConfigSchema, resolveGrafanaTarget } from "./config";
+export type { GrafanaConfig, GrafanaProfile } from "./config";
+
+// Ownership (#2946): chant's marker on a dashboard.grafana.app resource.
+export {
+  GRAFANA_OWNERSHIP_KEYS,
+  DEFAULT_PROVIDER_NAME,
+  grafanaOwnershipLabels,
+  dashboardOwnership,
+} from "./ownership";
+
+// The HTTP client observe and export share, for the API applier (#2948).
+export { GrafanaClient, GrafanaApiError, grafanaHttp, namespaceOf, statusVerdict } from "./api/client";
+export type { GrafanaAuth, GrafanaHttp, GrafanaResponse, GrafanaTarget, StatusVerdict } from "./api/client";
+export { bindGrafana, classifyGrafanaFailure, GrafanaBindingError } from "./api/bind";
+
+// The API applier (#2948): the typed Op step, and the pieces an embedding
+// caller composes (the activity itself is `./op/activities`).
+export { grafanaApply } from "./op/builders";
+export { applyGrafana, planFromDashboards, GRAFANA_APPLY_KINDS } from "./api/apply";
+export type { GrafanaApplyPlan, GrafanaApplyOutcome, DashboardPlan, BuiltDashboardInput } from "./api/apply";
+export { folderUidFor, foldersForDashboards, resolveFolders, liveFolderPath, type FolderPlan, type ResolvedFolders } from "./api/folders";
+
+// The Grafana RBAC actions a service account needs to observe, apply and prune.
+export { GrafanaActions, grafanaActionsFor, type GrafanaAccessLevel } from "./actions/index";