@intentius/chant-lexicon-grafana 0.98.0 → 0.100.0

package/dist/composites/slo-alert-rules.d.ts

@@ -0,0 +1,92 @@
+/**
+ * `SloAlertRules`: an `Slo`'s multiwindow, multi-burn-rate alerts as
+ * Grafana-managed alert rules, for teams that page from Grafana rather
+ * than from Prometheus and Alertmanager.
+ *
+ * The windows, factors, thresholds and labels come from the prometheus
+ * lexicon's `sloMetrics()`, the same numbers the `Slo`'s own Prometheus
+ * alerts use. Each burn-rate pair becomes one rule that reads the two
+ * error ratios the `Slo` records (`slo:sli_error:ratio_rate<window>`) as
+ * instant Prometheus queries, and a math expression that holds while both
+ * are above the pair's threshold:
+ *
+ *     A = slo:sli_error:ratio_rate1h{slo="checkout"}
+ *     B = slo:sli_error:ratio_rate5m{slo="checkout"}
+ *     C = $A > 0.0144 && $B > 0.0144        (condition)
+ *
+ * So the `Slo`'s rule group must be loaded into the Prometheus the rules
+ * query: the recording rules are what make a 3-day window cheap to
+ * evaluate every minute.
+ */
+import { type CompositeInstance } from "@intentius/chant/composite";
+import { type SloInstance, type SloMetrics } from "@intentius/chant-lexicon-prometheus/composites/slo";
+import type { RuleGroupEntity } from "@intentius/chant-lexicon-prometheus/rules";
+import { type AlertRuleGroupEntity, type ContactPointEntity, type ExecErrState, type NoDataState } from "../alerting.js";
+import { type DatasourceInput } from "../query.js";
+export interface SloAlertRulesProps {
+    /** The `Slo(...)` the rules alert on, its rule group, or what `sloMetrics()` returned for it. It must have alerting on. */
+    slo: SloInstance | RuleGroupEntity | SloMetrics;
+    /** The Prometheus holding the `Slo`'s recorded series: a declared `Datasource`, an `ExternalDatasource`, or `{ type: "prometheus", uid }`. */
+    datasource: DatasourceInput<"prometheus">;
+    /** The Grafana folder the rules are stored in, by title. */
+    folder: string;
+    /** The rule group's name. Defaults to the `Slo`'s group name, `slo-<name>`. */
+    group?: string;
+    /** How often the rules are evaluated, a multiple of 10s. Defaults to `1m`. */
+    interval?: string;
+    /**
+     * Send the alerts straight to this contact point. Left out, they go
+     * through the notification policy tree, which can route on the
+     * `severity` label (`page` or `ticket` by default).
+     */
+    contactPoint?: ContactPointEntity | string;
+    /** How long a pair must hold before its alert fires. Default: none; the short window already filters blips. */
+    for?: string;
+    /** More labels on every rule, e.g. `team`. */
+    labels?: Record<string, string>;
+    /** More annotations on every rule, e.g. `runbook_url`. */
+    annotations?: Record<string, string>;
+    /** What no data does. Defaults to `OK`: no recorded ratio means no traffic, so no budget is burning. */
+    noDataState?: NoDataState;
+    /** What a query error does. Defaults to `Error`. */
+    execErrState?: ExecErrState;
+}
+export type SloAlertRulesMembers = {
+    /** One rule per burn-rate pair, page tier first. */
+    rules: AlertRuleGroupEntity;
+};
+/** What `SloAlertRules(...)` returns: its rule group, as `rules`. */
+export type SloAlertRulesInstance = CompositeInstance<SloAlertRulesMembers> & SloAlertRulesMembers;
+/** The queries and condition of each burn-rate rule, from `sloMetrics()`. Exposed for tests and for rules of your own. */
+export declare function sloAlertQueries(m: SloMetrics): {
+    uid: string;
+    longExpr: string;
+    shortExpr: string;
+    condition: string;
+    tier: "page" | "ticket";
+    severity: string;
+    long: string;
+    short: string;
+    factor: number;
+    threshold: number;
+    longRecord: string;
+    shortRecord: string;
+    alert: string;
+    labels: import("lexicons/prometheus/src/model").LabelSet;
+    exhaustsIn: string;
+}[];
+/**
+ * Grafana-managed burn-rate alerts for an `Slo`: one rule per window pair,
+ * with the labels and annotations the `Slo`'s Prometheus alerts carry.
+ *
+ * @example
+ * ```ts
+ * import { Slo } from "@intentius/chant-lexicon-prometheus";
+ * import { SloAlertRules } from "@intentius/chant-lexicon-grafana";
+ *
+ * export const checkout = Slo({ name: "checkout", objective: 0.999, window: "30d", sli: { ... } });
+ * export const checkoutAlerts = SloAlertRules({ slo: checkout, datasource: prometheus, folder: "SLOs" });
+ * ```
+ */
+export declare const SloAlertRules: import("@intentius/chant/composite").CompositeDefinition<SloAlertRulesProps, SloAlertRulesMembers>;
+//# sourceMappingURL=slo-alert-rules.d.ts.map

package/dist/composites/slo-alert-rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slo-alert-rules.d.ts","sourceRoot":"","sources":["../../src/composites/slo-alert-rules.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAa,KAAK,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAC/E,OAAO,EAAc,KAAK,WAAW,EAAE,KAAK,UAAU,EAAE,MAAM,oDAAoD,CAAC;AACnH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAIL,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,EACvB,KAAK,YAAY,EACjB,KAAK,WAAW,EACjB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAa,KAAK,eAAe,EAAE,MAAM,UAAU,CAAC;AAI3D,MAAM,WAAW,kBAAkB;IACjC,2HAA2H;IAC3H,GAAG,EAAE,WAAW,GAAG,eAAe,GAAG,UAAU,CAAC;IAChD,8IAA8I;IAC9I,UAAU,EAAE,eAAe,CAAC,YAAY,CAAC,CAAC;IAC1C,4DAA4D;IAC5D,MAAM,EAAE,MAAM,CAAC;IACf,+EAA+E;IAC/E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,YAAY,CAAC,EAAE,kBAAkB,GAAG,MAAM,CAAC;IAC3C,+GAA+G;IAC/G,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,wGAAwG;IACxG,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,oDAAoD;IACpD,YAAY,CAAC,EAAE,YAAY,CAAC;CAC7B;AAED,MAAM,MAAM,oBAAoB,GAAG;IACjC,oDAAoD;IACpD,KAAK,EAAE,oBAAoB,CAAC;CAC7B,CAAC;AAEF,qEAAqE;AACrE,MAAM,MAAM,qBAAqB,GAAG,iBAAiB,CAAC,oBAAoB,CAAC,GAAG,oBAAoB,CAAC;AAYnG,0HAA0H;AAC1H,wBAAgB,eAAe,CAAC,CAAC,EAAE,UAAU;;;;;;;;;;;;;;;;IAQ5C;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,aAAa,oGAwCP,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,111 @@
+/**
+ * The `grafana` namespace in `chant.config.ts` (#2946): which Grafana each
+ * chant environment observes, exports from and (#2948) applies to.
+ *
+ * ```ts
+ * import type { ChantConfig } from "@intentius/chant/config";
+ * import "@intentius/chant-lexicon-grafana";   // brings the `grafana` key into ChantConfig
+ *
+ * export default {
+ *   lexicons: ["grafana"],
+ *   grafana: {
+ *     profiles: {
+ *       staging: { url: "https://grafana.staging.example.com", token: { env: "GRAFANA_STAGING_TOKEN" } },
+ *       prod: { url: "https://grafana.example.com", token: { env: "GRAFANA_PROD_TOKEN" }, orgId: 2 },
+ *     },
+ *   },
+ * } satisfies ChantConfig;
+ * ```
+ *
+ * A profile is keyed by chant environment, as `k8s.profiles.<env>` is.
+ * Credentials are named by their environment variable, never written in
+ * the config. An environment with no profile falls back to `GRAFANA_URL`
+ * with `GRAFANA_TOKEN`, or `GRAFANA_USER` and `GRAFANA_PASSWORD` (see
+ * `resolveGrafanaTarget`).
+ *
+ * One schema, three consumers, as in the fountain lexicon: core validates the
+ * namespace against it at load, the type is derived from it, and that type
+ * augments `ChantConfig`.
+ */
+import { z } from "zod";
+import type { ChantConfig } from "@intentius/chant/config";
+import type { GrafanaTarget } from "./api/client.js";
+export declare const grafanaProfileSchema: z.ZodObject<{
+    /** Base URL of the Grafana instance. */
+    url: z.ZodString;
+    /** A service account token, named by its environment variable. */
+    token: z.ZodOptional<z.ZodObject<{
+        env: z.ZodString;
+    }, z.core.$strict>>;
+    /** Basic auth, each half named by its environment variable. For a local instance; use a token elsewhere. */
+    basicAuth: z.ZodOptional<z.ZodObject<{
+        user: z.ZodObject<{
+            env: z.ZodString;
+        }, z.core.$strict>;
+        password: z.ZodObject<{
+            env: z.ZodString;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+    /** Organisation id. Defaults to 1. */
+    orgId: z.ZodOptional<z.ZodNumber>;
+    /** The `dashboard.grafana.app` namespace, when it is not `default` / `org-<id>` (Grafana Cloud: `stacks-<id>`). */
+    namespace: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const grafanaConfigSchema: z.ZodObject<{
+    /** One Grafana per chant environment. */
+    profiles: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        /** Base URL of the Grafana instance. */
+        url: z.ZodString;
+        /** A service account token, named by its environment variable. */
+        token: z.ZodOptional<z.ZodObject<{
+            env: z.ZodString;
+        }, z.core.$strict>>;
+        /** Basic auth, each half named by its environment variable. For a local instance; use a token elsewhere. */
+        basicAuth: z.ZodOptional<z.ZodObject<{
+            user: z.ZodObject<{
+                env: z.ZodString;
+            }, z.core.$strict>;
+            password: z.ZodObject<{
+                env: z.ZodString;
+            }, z.core.$strict>;
+        }, z.core.$strict>>;
+        /** Organisation id. Defaults to 1. */
+        orgId: z.ZodOptional<z.ZodNumber>;
+        /** The `dashboard.grafana.app` namespace, when it is not `default` / `org-<id>` (Grafana Cloud: `stacks-<id>`). */
+        namespace: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type GrafanaProfile = z.infer<typeof grafanaProfileSchema>;
+export type GrafanaConfig = z.infer<typeof grafanaConfigSchema>;
+declare module "@intentius/chant/config" {
+    interface ChantConfig {
+        grafana?: GrafanaConfig;
+    }
+}
+/** Compile-time proof that the augmentation reaches `ChantConfig`. */
+export type GrafanaConfigNamespace = NonNullable<ChantConfig["grafana"]>;
+/** Why no target could be resolved, in the observation vocabulary. */
+export interface UnresolvedTarget {
+    readonly reason: "no-binding" | "no-credentials";
+    readonly detail: string;
+}
+declare function isUnresolved(v: GrafanaTarget | UnresolvedTarget): v is UnresolvedTarget;
+export { isUnresolved as isUnresolvedTarget };
+/**
+ * The Grafana an environment reads from. Pure: `config` and `env` are
+ * passed in.
+ *
+ * 1. `grafana.profiles.<environment>`. A profile that names a credential
+ *    variable which is not set is `no-credentials`, not an anonymous read:
+ *    the profile said how to authenticate.
+ * 2. `GRAFANA_URL`, with `GRAFANA_TOKEN`, or `GRAFANA_USER` and
+ *    `GRAFANA_PASSWORD`, or neither (an instance with anonymous access; a
+ *    refused read is then `no-credentials`).
+ * 3. Otherwise `no-binding`.
+ */
+export declare function resolveGrafanaTarget(input: {
+    environment?: string;
+    config?: Pick<ChantConfig, "grafana">;
+    env?: Record<string, string | undefined>;
+}): GrafanaTarget | UnresolvedTarget;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,KAAK,EAAe,aAAa,EAAE,MAAM,cAAc,CAAC;AAI/D,eAAO,MAAM,oBAAoB;IAC/B,wCAAwC;;IAExC,kEAAkE;;;;IAElE,4GAA4G;;;;;;;;;IAE5G,sCAAsC;;IAEtC,mHAAmH;;kBAEnH,CAAC;AAEH,eAAO,MAAM,mBAAmB;IAC9B,yCAAyC;;QAbzC,wCAAwC;;QAExC,kEAAkE;;;;QAElE,4GAA4G;;;;;;;;;QAE5G,sCAAsC;;QAEtC,mHAAmH;;;kBAOnH,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAClE,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,OAAO,QAAQ,yBAAyB,CAAC;IACvC,UAAU,WAAW;QACnB,OAAO,CAAC,EAAE,aAAa,CAAC;KACzB;CACF;AAED,sEAAsE;AACtE,MAAM,MAAM,sBAAsB,GAAG,WAAW,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC,CAAC;AAEzE,sEAAsE;AACtE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,YAAY,GAAG,gBAAgB,CAAC;IACjD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,iBAAS,YAAY,CAAC,CAAC,EAAE,aAAa,GAAG,gBAAgB,GAAG,CAAC,IAAI,gBAAgB,CAEhF;AAED,OAAO,EAAE,YAAY,IAAI,kBAAkB,EAAE,CAAC;AAE9C;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE;IAC1C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,IAAI,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;IACtC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;CAC1C,GAAG,aAAa,GAAG,gBAAgB,CA2CnC"}

package/dist/contact-point-secrets.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The contact point settings Grafana stores encrypted, per integration: the
+ * options marked `secure` by `GET /api/alert-notifiers?version=2` on
+ * `grafana/grafana:13.2.2` (commit 1bea008f; the same list on 12.4.11).
+ * Nested settings are dotted paths (`tlsConfig.clientKey`).
+ *
+ * GRAF002 flags a literal at one of these paths, and the importer replaces
+ * the `[REDACTED]` that an export without secrets writes there.
+ */
+export declare const CONTACT_POINT_SECRET_SETTINGS: Readonly<Record<string, readonly string[]>>;
+/** How Grafana provisioning reads a value from outside the file: `$VAR`, `${VAR}`, `$__env{…}`, `$__file{…}`, `$__vault{…}`. */
+export declare const EXPANDED_VALUE: RegExp;
+/** What an export without secrets writes in place of each one. */
+export declare const REDACTED = "[REDACTED]";
+/** The secret settings of one receiver present in `settings`, with their values: `[path, value]`. */
+export declare function secretSettings(type: string, settings: Record<string, unknown>): Array<[string, unknown]>;
+//# sourceMappingURL=contact-point-secrets.d.ts.map

package/dist/contact-point-secrets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contact-point-secrets.d.ts","sourceRoot":"","sources":["../src/contact-point-secrets.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,eAAO,MAAM,6BAA6B,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAoCpF,CAAC;AAEH,gIAAgI;AAChI,eAAO,MAAM,cAAc,QAAsF,CAAC;AAElH,kEAAkE;AAClE,eAAO,MAAM,QAAQ,eAAe,CAAC;AAErC,qGAAqG;AACrG,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAQxG"}

package/dist/dashboard.d.ts

@@ -10,6 +10,8 @@ import type { Declarable } from "@intentius/chant/declarable";
 import type { PanelEntity, RowEntity } from "./panels.js";
 import type { VariableEntity } from "./variables.js";
 import type { DashboardLink, TimePickerConfig } from "./schema/dashboard.gen.js";
+import { type FolderEntity } from "./folder.js";
+import type { AnnotationInput } from "./annotations.js";
 /** A dashboard link: `title` and `type` required, the rest defaulted as Grafana's editor would. */
 export type DashboardLinkInput = Partial<DashboardLink> & Pick<DashboardLink, "title" | "type">;
 export interface DashboardProps {
@@ -39,22 +41,51 @@ export interface DashboardProps {
     graphTooltip?: "default" | "sharedCrosshair" | "sharedTooltip";
     /** Whether users may edit it in the UI. Defaults to true, as in Grafana. */
     editable?: boolean;
+    /**
+     * The dashboard schema version the JSON is written at. Leave it out for
+     * the pinned one (`DASHBOARD_SCHEMA_VERSION`). `chant import` sets it for
+     * a dashboard saved by an older Grafana, so Grafana still runs its
+     * migrations when it loads the rebuilt JSON.
+     */
+    schemaVersion?: number;
     variables?: VariableEntity<any>[];
     /** Panels and rows, top to bottom. A row's own `panels` follow it. */
     panels?: Array<PanelEntity<any, any> | RowEntity>;
     links?: DashboardLinkInput[];
     /**
-     * The Grafana folder to provision it into. Written as a subdirectory of
-     * `dashboards/`, which the provider maps to folders
-     * (`foldersFromFilesStructure`). Leave it out for the General folder.
+     * Annotation queries: events drawn on the dashboard's time series panels
+     * (deploys, incidents), each from a datasource. Grafana adds its own
+     * "Annotations & Alerts" query to every dashboard that has none with
+     * `builtIn: 1`, so leave that one out unless you change it.
      */
-    folder?: string;
+    annotations?: AnnotationInput[];
+    /**
+     * The Grafana folder: a path (`"Platform/Kubernetes"`) or a `Folder`,
+     * which pins the folder's uid. Written as a subdirectory of `dashboards/`,
+     * which the provider maps to folders (`foldersFromFilesStructure`); a path
+     * nests one directory in another, which Grafana 13.1 and later make a
+     * Kubernetes folder inside Platform, and earlier versions use only the
+     * last level (GRAF109 warns). The API applier creates each level with its
+     * uid. Leave it out for the General folder.
+     */
+    folder?: string | FolderEntity;
 }
+/** A dashboard's props as the entity holds them: `folder` is always the path, and a `Folder` given for it is `folderEntity`. */
+export type DashboardEntityProps = Omit<DashboardProps, "folder"> & {
+    folder?: string;
+};
 export interface DashboardEntity extends Declarable {
-    readonly props: DashboardProps;
+    readonly props: DashboardEntityProps;
+    /** The `Folder` the dashboard was given, when it was given one rather than a path. */
+    readonly folderEntity?: FolderEntity;
 }
 export declare const DASHBOARD_TYPE = "Grafana::Dashboard";
-/** A Grafana dashboard. */
+/**
+ * A Grafana dashboard. A `Folder` given as its `folder` is held as the
+ * folder's path, so everything that reads the dashboard's props (the build,
+ * the checks, observation's diff) sees one form; the `Folder` itself, for its
+ * uid, is `folderEntity`.
+ */
 export declare const Dashboard: new (props: DashboardProps) => DashboardEntity;
 export declare function isDashboardEntity(value: unknown): value is DashboardEntity;
 /** Where Grafana finds the dashboard files by default: mount `dashboards/` here. */
@@ -63,8 +94,15 @@ export interface DashboardProviderProps {
     /** Provider name, unique in the provisioning file. */
     name: string;
     orgId?: number;
-    /** Folder for dashboards not in a subdirectory. */
-    folder?: string;
+    /**
+     * Put every dashboard this provider loads in this folder: a title, or a
+     * root-level `Folder`, whose title and uid are written as `folder` and
+     * `folderUid` (Grafana creates a provider's folder at the root, so a
+     * nested `Folder` is refused). Setting it (or `folderUid`) turns
+     * `foldersFromFilesStructure` off by default, so each dashboard's own
+     * `folder` is ignored (GRAF109 warns).
+     */
+    folder?: string | FolderEntity;
     folderUid?: string;
     /** Where the `dashboards/` output is mounted in the Grafana container. Defaults to `/var/lib/grafana/dashboards`. */
     path?: string;
@@ -74,8 +112,12 @@ export interface DashboardProviderProps {
     allowUiUpdates?: boolean;
     updateIntervalSeconds?: number;
 }
+/** A provider's props as the entity holds them: a `Folder` given for `folder` is written out as `folder` and `folderUid`. */
+export type DashboardProviderEntityProps = Omit<DashboardProviderProps, "folder"> & {
+    folder?: string;
+};
 export interface DashboardProviderEntity extends Declarable {
-    readonly props: DashboardProviderProps;
+    readonly props: DashboardProviderEntityProps;
 }
 export declare const DASHBOARD_PROVIDER_TYPE = "Grafana::DashboardProvider";
 /** An entry in the dashboard provisioning file. Optional: a default one is written when none is declared. */

package/dist/dashboard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dashboard.d.ts","sourceRoot":"","sources":["../src/dashboard.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"dashboard.d.ts","sourceRoot":"","sources":["../src/dashboard.ts"],"names":[],"mappings":"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"}

package/dist/datasource-refs.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Which datasource each panel, query and query variable in built dashboard
+ * JSON sends its request to.
+ *
+ * GRAF101 and GRAF102 use this to check references against the datasources
+ * a build knows about: the ones it provisions (`Datasource`) and the ones it
+ * only references (`ExternalDatasource`). Any other check that needs to know
+ * which plugin runs a query (a PromQL syntax check only wants the queries
+ * that reach a Prometheus) can call `datasourceUses()` and read
+ * `resolved.type`.
+ */
+import type { ExternalDatasourceRecord, ProvisionedDatasource } from "./build.js";
+type Json = Record<string, unknown>;
+/** A `{ type, uid }` datasource reference as dashboard JSON holds it. */
+export interface DatasourceRefJson {
+    type?: string;
+    uid?: string;
+}
+/** A datasource the build knows by uid: provisioned by it, or declared external. */
+export interface KnownDatasource {
+    uid: string;
+    type: string;
+    name?: string;
+    /** Declared with `ExternalDatasource`: referenced, not provisioned. */
+    external: boolean;
+}
+/**
+ * Where a reference leads.
+ *
+ * - `declared`: a known datasource; `type` is its plugin type.
+ * - `variable`: a `${name}` uid; `type` is the datasource variable's plugin type, else the ref's own.
+ * - `builtin`: one of Grafana's pseudo-datasources (`-- Mixed --`, `-- Dashboard --`, `grafana`).
+ * - `undeclared`: a uid the build does not know; `type` is whatever the ref says.
+ * - `default`: no uid, so Grafana picks its default datasource; `type` is the ref's, if it has one.
+ */
+export type ResolvedDatasource = {
+    kind: "declared";
+    type: string;
+    datasource: KnownDatasource;
+} | {
+    kind: "variable";
+    type?: string;
+    variable: string;
+    declared: boolean;
+} | {
+    kind: "builtin";
+    type?: string;
+} | {
+    kind: "undeclared";
+    type?: string;
+    uid: string;
+} | {
+    kind: "default";
+    type?: string;
+};
+/** One place a dashboard names, or inherits, a datasource. */
+export interface DatasourceUse {
+    /** A panel's own `datasource`, one of its queries (`targets`), a query, ad hoc or group by variable, or an annotation query. */
+    kind: "panel" | "query" | "variable" | "annotation";
+    /** A human description, e.g. `panel "Latency" (id 3) query B`. */
+    where: string;
+    panel?: Json;
+    target?: Json;
+    variable?: Json;
+    annotation?: Json;
+    /** The ref written on this panel, query, variable or annotation; unset when a query inherits its panel's. */
+    ref?: DatasourceRefJson;
+    /** Where the request goes: the query's own ref, else its panel's. */
+    resolved: ResolvedDatasource;
+}
+/** Every datasource a build knows by uid. A provisioned one wins over an external one of the same uid (GRAF104 reports the clash). */
+export declare function knownDatasources(datasources: readonly ProvisionedDatasource[], external?: readonly ExternalDatasourceRecord[]): Map<string, KnownDatasource>;
+export interface PanelInfo {
+    panel: Json;
+    /** Panels inside a collapsed row are laid out in their own group. */
+    group: string;
+}
+/** Every panel of a dashboard, including those inside collapsed rows, and the rows themselves. */
+export declare function panelsOf(dashboard: Json): PanelInfo[];
+export declare function describePanel(panel: Json): string;
+/** A dashboard's `templating.list`. */
+export declare function variablesOf(dashboard: Json): Json[];
+/** Every variable name referenced in a string. */
+export declare function variableReferences(text: string): string[];
+/** Grafana's own pseudo-datasources, which no build declares. */
+export declare function isPseudoRef(ref: DatasourceRefJson): boolean;
+/** Where one reference leads, given the dashboard's datasource variables and the known datasources. */
+export declare function resolveDatasourceRef(ref: DatasourceRefJson | undefined, dsVariables: ReadonlyMap<string, Json>, known: ReadonlyMap<string, KnownDatasource>): ResolvedDatasource;
+/** A dashboard's `annotations.list`. */
+export declare function annotationsOf(dashboard: Json): Json[];
+/**
+ * Every place a dashboard names or inherits a datasource: each panel's own
+ * ref, each query (with its own ref, or its panel's when it has none), each
+ * query, ad hoc and group by variable, and each annotation query with a datasource. Rows are left
+ * out; their panels carry the ref.
+ */
+export declare function datasourceUses(dashboard: Json, known: ReadonlyMap<string, KnownDatasource>): DatasourceUse[];
+export {};
+//# sourceMappingURL=datasource-refs.d.ts.map

package/dist/datasource-refs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"datasource-refs.d.ts","sourceRoot":"","sources":["../src/datasource-refs.ts"],"names":[],"mappings":"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"}