@intentius/chant-lexicon-grafana 0.99.0 → 0.100.0

package/dist/spec/schemas.d.ts

@@ -2,14 +2,15 @@
  * Read the vendored Grafana schemas (`src/spec/schemas/*.jsonschema.json`), check
  * them against the digests in `GRAFANA_SCHEMA_PIN`, and apply the correction
  * overlay (`src/spec/overlay/`, see `./overlay.ts`) on top.
+ *
+ * This is the source side, for `npm run generate`, the lexicon's own
+ * validate step, the importer's tests and the fetch scripts: it reads files
+ * next to this module. Nothing a build or lint runs imports it. Validation
+ * reads the generated `./schemas.gen.ts`, which generate writes from
+ * {@link loadSchema}.
  */
 import { type SchemaName, type VendoredSchemaName } from "../pin.js";
-/**
- * Where the vendored files live: beside this module, under `src/`, so they
- * ship with the source the package runs from and GRAF107 can read them.
- * A function, not a module-scope constant, so edge bundles that import the
- * lexicon never evaluate a filesystem path at load.
- */
+/** Where the vendored files live: beside this module, under `src/`. */
 export declare function schemasDir(): string;
 export declare function schemaPath(name: VendoredSchemaName): string;
 export declare function sha256(text: string | Buffer): string;
@@ -19,7 +20,8 @@ export declare function readSchemaText(name: VendoredSchemaName): string;
 export declare function loadVendoredSchema(name: VendoredSchemaName): Record<string, unknown>;
 /**
  * One schema as the lexicon uses it: the vendored file with its overlay
- * applied (cached per process). Types, GRAF107 and validation all read this.
+ * applied (cached per process). Generate writes the types and
+ * `./schemas.gen.ts` from this, so GRAF107 sees the same schema.
  */
 export declare function loadSchema(name: SchemaName): Record<string, unknown>;
 /** Vendored files whose digest does not match the pin, with what was found. */

package/dist/spec/schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../src/spec/schemas.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,OAAO,EAA6C,KAAK,UAAU,EAAE,KAAK,kBAAkB,EAAE,MAAM,QAAQ,CAAC;AAG7G;;;;;GAKG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,kBAAkB,GAAG,MAAM,CAE3D;AAED,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAEpD;AAED,4CAA4C;AAC5C,wBAAgB,cAAc,CAAC,IAAI,EAAE,kBAAkB,GAAG,MAAM,CAE/D;AAED,0EAA0E;AAC1E,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEpF;AAID;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CASpE;AAED,+EAA+E;AAC/E,wBAAgB,gBAAgB,IAAI,KAAK,CAAC;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAQxG"}
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../src/spec/schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH,OAAO,EAA6C,KAAK,UAAU,EAAE,KAAK,kBAAkB,EAAE,MAAM,QAAQ,CAAC;AAG7G,uEAAuE;AACvE,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,kBAAkB,GAAG,MAAM,CAE3D;AAED,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAEpD;AAED,4CAA4C;AAC5C,wBAAgB,cAAc,CAAC,IAAI,EAAE,kBAAkB,GAAG,MAAM,CAE/D;AAED,0EAA0E;AAC1E,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEpF;AAID;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CASpE;AAED,+EAA+E;AAC/E,wBAAgB,gBAAgB,IAAI,KAAK,CAAC;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAQxG"}

package/dist/spec/schemas.gen.d.ts

@@ -0,0 +1,3 @@
+import type { SchemaName } from "../pin.js";
+export declare const SCHEMA_JSON: Readonly<Record<SchemaName, string>>;
+//# sourceMappingURL=schemas.gen.d.ts.map

package/dist/spec/schemas.gen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.gen.d.ts","sourceRoot":"","sources":["../../src/spec/schemas.gen.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAEzC,eAAO,MAAM,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CA8B5D,CAAC"}

package/dist/validate-alerting.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate-alerting.d.ts","sourceRoot":"","sources":["../src/validate-alerting.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAKzD,KAAK,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEpC,sEAAsE;AACtE,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,IAAI,CAAC;CACZ;AAED,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;AAE1F,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,iBAAiB,CAAC;IACxB,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,6FAA6F;AAC7F,eAAO,MAAM,sBAAsB,EAAE,WAAW,CAAC,MAAM,CAAsC,CAAC;AAe9F,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,IAAI,CAAC;IACX,KAAK,EAAE,IAAI,CAAC;IACZ,oCAAoC;IACpC,KAAK,EAAE,MAAM,CAAC;CACf;AAED,kDAAkD;AAClD,wBAAgB,UAAU,CAAC,IAAI,EAAE,SAAS,WAAW,EAAE,GAAG,QAAQ,EAAE,CAUnE;AAYD,sCAAsC;AACtC,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,IAAI,GAAG,MAAM,EAAE,CAwBtD;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,WAAW,EAAE,GAAG,aAAa,EAAE,CA0C9E;AAaD,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,SAAS,WAAW,EAAE,EAAE,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,eAAe,CAAC,GAAG,aAAa,EAAE,CA6C/H;AAED,0FAA0F;AAC1F,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,WAAW,EAAE,EAAE,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,eAAe,CAAC,GAAG,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAajK;AAED,yFAAyF;AACzF,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,WAAW,EAAE,EAAE,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,eAAe,CAAC,GAAG,aAAa,EAAE,CAO1H;AAqBD,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,SAAS,WAAW,EAAE,GAAG,aAAa,EAAE,CAiEnF;AAaD,wGAAwG;AACxG,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAIxC,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,SAAS,WAAW,EAAE,GAAG,aAAa,EAAE,CA2EnF"}
+{"version":3,"file":"validate-alerting.d.ts","sourceRoot":"","sources":["../src/validate-alerting.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAKzD,KAAK,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEpC,sEAAsE;AACtE,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,IAAI,CAAC;CACZ;AAED,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;AAE1F,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,iBAAiB,CAAC;IACxB,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,6FAA6F;AAC7F,eAAO,MAAM,sBAAsB,EAAE,WAAW,CAAC,MAAM,CAAsC,CAAC;AAe9F,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,IAAI,CAAC;IACX,KAAK,EAAE,IAAI,CAAC;IACZ,oCAAoC;IACpC,KAAK,EAAE,MAAM,CAAC;CACf;AAED,kDAAkD;AAClD,wBAAgB,UAAU,CAAC,IAAI,EAAE,SAAS,WAAW,EAAE,GAAG,QAAQ,EAAE,CAUnE;AAYD,sCAAsC;AACtC,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,IAAI,GAAG,MAAM,EAAE,CAwBtD;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,WAAW,EAAE,GAAG,aAAa,EAAE,CA4C9E;AAaD,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,SAAS,WAAW,EAAE,EAAE,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,eAAe,CAAC,GAAG,aAAa,EAAE,CA6C/H;AAED,0FAA0F;AAC1F,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,WAAW,EAAE,EAAE,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,eAAe,CAAC,GAAG,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAajK;AAED,yFAAyF;AACzF,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,WAAW,EAAE,EAAE,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,eAAe,CAAC,GAAG,aAAa,EAAE,CAO1H;AAqBD,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,SAAS,WAAW,EAAE,GAAG,aAAa,EAAE,CAiEnF;AAaD,wGAAwG;AACxG,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAIxC,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,SAAS,WAAW,EAAE,GAAG,aAAa,EAAE,CA2EnF"}

package/dist/validate-output.d.ts

@@ -1,5 +1,5 @@
 /**
- * The checks behind GRAF101-GRAF109, GRAF111-GRAF114 and GRAF115, as plain
+ * The checks behind GRAF101-GRAF110, GRAF111-GRAF114 and GRAF115, as plain
  * functions over built Grafana output: dashboard JSON documents, provisioned
  * datasources, dashboard providers and alerting provisioning files (the
  * alerting checks are in `validate-alerting.ts`). The
@@ -16,7 +16,7 @@
 import type { ExternalDatasourceRecord, ProvisionedDatasource } from "./build.js";
 import { variableReferences, type KnownDatasource } from "./datasource-refs.js";
 import { type AlertingDoc } from "./validate-alerting.js";
-export type GrafanaIssueCode = "GRAF101" | "GRAF102" | "GRAF103" | "GRAF104" | "GRAF105" | "GRAF106" | "GRAF107" | "GRAF108" | "GRAF109" | "GRAF111" | "GRAF112" | "GRAF113" | "GRAF114" | "GRAF115";
+export type GrafanaIssueCode = "GRAF101" | "GRAF102" | "GRAF103" | "GRAF104" | "GRAF105" | "GRAF106" | "GRAF107" | "GRAF108" | "GRAF109" | "GRAF110" | "GRAF111" | "GRAF112" | "GRAF113" | "GRAF114" | "GRAF115";
 export interface GrafanaIssue {
     code: GrafanaIssueCode;
     severity: "error" | "warning";
@@ -39,6 +39,18 @@ export interface GrafanaArtifacts {
     providers?: Array<Record<string, unknown>>;
     /** Alerting provisioning files (rule groups, contact points, policies, mute timings, templates). */
     alerting?: AlertingDoc[];
+    /** The folders the build resolved (its index's `folders`): each level of each dashboard's folder path, and every `Folder`. */
+    folders?: Array<{
+        uid: string;
+        title: string;
+        path?: string;
+        parentUid?: string;
+    }>;
+    /** `deleteDatasources` entries of datasource provisioning files. */
+    deleteDatasources?: Array<{
+        name: string;
+        orgId?: number;
+    }>;
 }
 export type { AlertingDoc };
 export { variableReferences };
@@ -63,6 +75,7 @@ export declare function checkSchema(a: GrafanaArtifacts): GrafanaIssue[];
  * not parsed.
  */
 export declare function checkPromqlSyntax(a: GrafanaArtifacts): GrafanaIssue[];
+export declare function checkRepeats(a: GrafanaArtifacts): GrafanaIssue[];
 /** Every unit a panel sets, with where: field defaults, `unit` overrides, heatmap axes and cells, and a legacy graph panel's y-axes. */
 export declare function panelUnits(panel: Json): Array<{
     where: string;

package/dist/validate-output.d.ts.map

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

package/dist/validate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAiB,cAAc,EAAE,MAAM,mCAAmC,CAAC;AASvF,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AAEvF,0DAA0D;AAC1D,eAAO,MAAM,cAAc,UAoC1B,CAAC;AAIF,wBAAsB,QAAQ,IAAI,OAAO,CAAC,cAAc,CAAC,CA2DxD"}
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAiB,cAAc,EAAE,MAAM,mCAAmC,CAAC;AASvF,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AAEvF,0DAA0D;AAC1D,eAAO,MAAM,cAAc,UAkD1B,CAAC;AAIF,wBAAsB,QAAQ,IAAI,OAAO,CAAC,cAAc,CAAC,CA2DxD"}

package/dist/validation.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `@intentius/chant-lexicon-grafana/validation`: the GRAF101-GRAF115 checks
+ * as plain functions over built Grafana output, and the schema validation
+ * behind GRAF107, for code that checks dashboards without a build.
+ *
+ * These are not on the package root, so importing the lexicon to declare
+ * dashboards does not load them. `chant build` and `chant lint` run the same
+ * checks through the plugin's post-synth checks. ajv is loaded the first time
+ * a schema is checked, and the schemas come from a generated module rather
+ * than files, so this works bundled.
+ */
+export { validateGrafanaOutput, issuesFor, knownDatasourcesOf, type GrafanaIssue, type GrafanaIssueCode, type GrafanaArtifacts, type DashboardDoc, } from "./validate-output.js";
+export { validateDashboardSchema, validateExpressionSchema, schemaValidationUnavailable, type SchemaProblem, } from "./schema-validate.js";
+//# sourceMappingURL=validation.d.ts.map

package/dist/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EACL,qBAAqB,EACrB,SAAS,EACT,kBAAkB,EAClB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,YAAY,GAClB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,uBAAuB,EACvB,wBAAwB,EACxB,2BAA2B,EAC3B,KAAK,aAAa,GACnB,MAAM,mBAAmB,CAAC"}

package/dist/variables.d.ts

@@ -1,6 +1,6 @@
 /**
  * Dashboard variables (Grafana's "templating"): query, custom, interval,
- * datasource, constant and textbox.
+ * datasource, constant, textbox, ad hoc filters, group by and switch.
  *
  * A variable is declared on its own and listed in a dashboard's
  * `variables`. Queries reference it as `$name` or `${name}` in their
@@ -10,8 +10,10 @@
  */
 import type { Declarable } from "@intentius/chant/declarable";
 import type { DatasourceEntity, DatasourceRef, ExternalDatasourceEntity } from "./datasource.js";
-import type { VariableOption } from "./schema/dashboard.gen.js";
-export type VariableKind = "query" | "custom" | "interval" | "datasource" | "constant" | "textbox";
+import type { AdHocFilter, VariableOption } from "./schema/dashboard.gen.js";
+export type VariableKind = "query" | "custom" | "interval" | "datasource" | "constant" | "textbox" | "adhoc" | "groupby" | "switch";
+/** The kinds Grafana can repeat a panel or row over: the ones that hold a list of values (`MultiValueVariable` in @grafana/scenes). */
+export declare const MULTI_VALUE_KINDS: ReadonlySet<string>;
 /** Where the variable shows: with its label, without it, or not at all. */
 export type VariableHide = "label" | "valueOnly" | "hidden";
 interface CommonVariableProps {
@@ -33,10 +35,47 @@ interface MultiValueProps {
 }
 /** A variable anything can hold before its datasource is known: its own datasource ref or a datasource variable. */
 export type VariableDatasource = DatasourceEntity<any> | ExternalDatasourceEntity<any> | DatasourceRef | DatasourceVariableEntity<any>;
+/**
+ * A variable query in the object form a datasource's variable editor
+ * writes. Grafana passes it to the datasource as it is, so any key the
+ * datasource reads may be here.
+ */
+export interface VariableQueryObject {
+    /** The query text, when the datasource has one (Prometheus, Loki, and most others). */
+    query?: string;
+    /** The editor's id for the query; Grafana writes e.g. `PrometheusVariableQueryEditor-VariableQuery`. */
+    refId?: string;
+    [key: string]: unknown;
+}
+/**
+ * A Prometheus variable query as Grafana's Prometheus variable editor
+ * writes it. `query` is the text Grafana runs (`label_values(up, job)`);
+ * the other fields let the editor show the query in its form again.
+ */
+export interface PrometheusVariableQuery extends VariableQueryObject {
+    query: string;
+    /** The editor's query type: 0 label names, 1 label values, 2 metrics, 3 query result, 4 series query, 5 classic query. */
+    qryType?: 0 | 1 | 2 | 3 | 4 | 5;
+    label?: string;
+    metric?: string;
+    seriesQuery?: string;
+    varQueryResult?: string;
+    labelFilters?: Array<{
+        label: string;
+        op: string;
+        value: string;
+    }>;
+}
 export interface QueryVariableProps extends CommonVariableProps, MultiValueProps {
     datasource: VariableDatasource;
-    /** The datasource's variable query, e.g. `label_values(up, job)` for Prometheus. */
-    query: string;
+    /**
+     * The datasource's variable query: a string (`label_values(up, job)` for
+     * Prometheus), or the object the datasource's variable editor writes
+     * (`{ query: "label_values(up, job)", qryType: 1 }`).
+     */
+    query: string | VariableQueryObject;
+    /** The text Grafana shows for the query in the variable list. Defaults to the query string. */
+    definition?: string;
     regex?: string;
     /** When to re-run the query. Defaults to on dashboard load. */
     refresh?: "never" | "onLoad" | "onTimeRangeChange";
@@ -70,6 +109,49 @@ export interface ConstantVariableProps extends Omit<CommonVariableProps, "hide">
 export interface TextboxVariableProps extends CommonVariableProps {
     value?: string;
 }
+/** One ad hoc filter: `key operator value`, e.g. `{ key: "namespace", operator: "=", value: "shop" }`. */
+export type AdhocFilter = AdHocFilter;
+/** A key an ad hoc or group by variable offers, in place of asking the datasource. */
+export interface VariableKeyOption {
+    text: string;
+    value?: string | number;
+    [key: string]: unknown;
+}
+export interface AdhocVariableProps extends CommonVariableProps {
+    /** The datasource whose queries get the filters, and which is asked for keys and values. */
+    datasource: VariableDatasource;
+    /** The filters applied when the dashboard loads. */
+    filters?: AdhocFilter[];
+    /** Filters that narrow the key and value lookups, not shown or applied to queries. */
+    baseFilters?: AdhocFilter[];
+    /** A fixed set of keys to offer instead of the datasource's. */
+    defaultKeys?: VariableKeyOption[];
+    /** Whether a key or value not in the list can be typed in. Grafana's default is true. */
+    allowCustomValue?: boolean;
+    /** Offer the group-by operator in the filter box (Grafana 13, behind the `dashboardUnifiedDrilldownControls` feature toggle). */
+    enableGroupBy?: boolean;
+}
+export interface GroupByVariableProps extends CommonVariableProps {
+    /** The datasource whose queries are grouped, and which is asked for the keys. */
+    datasource: VariableDatasource;
+    /** A fixed set of keys to offer instead of the datasource's: a key, or `{ text, value }`. */
+    options?: Array<string | {
+        text: string;
+        value: string;
+    }>;
+    /** The keys selected when the dashboard loads with none in the URL. */
+    defaultValue?: string[] | VariableOption;
+    /** Whether a key not in the list can be typed in. Grafana's default is true. */
+    allowCustomValue?: boolean;
+}
+export interface SwitchVariableProps extends Omit<CommonVariableProps, "current"> {
+    /** Whether the switch is on when the dashboard loads. Defaults to off. */
+    enabled?: boolean;
+    /** The value `$name` has when the switch is on. Defaults to `"true"`. */
+    enabledValue?: string;
+    /** The value `$name` has when the switch is off. Defaults to `"false"`. */
+    disabledValue?: string;
+}
 export interface VariableEntity<P = CommonVariableProps> extends Declarable {
     readonly props: P;
     readonly variableKind: VariableKind;
@@ -95,6 +177,21 @@ export declare const DatasourceVariable: {
 export declare const ConstantVariable: new (props: ConstantVariableProps) => VariableEntity<ConstantVariableProps>;
 /** A free-text box. */
 export declare const TextboxVariable: new (props: TextboxVariableProps) => VariableEntity<TextboxVariableProps>;
+/**
+ * Ad hoc filters: `key operator value` filters Grafana adds to every query
+ * sent to the variable's datasource (Prometheus, Loki, Elasticsearch,
+ * InfluxDB and others whose plugin supports them). Referenced by no query.
+ */
+export declare const AdhocVariable: new (props: AdhocVariableProps) => VariableEntity<AdhocVariableProps>;
+/**
+ * Group by: a choice of label keys Grafana adds as a grouping to every query
+ * sent to the variable's datasource. In Grafana 12.4 and 13.x it is
+ * experimental: with the `groupByVariable` feature toggle off, Grafana
+ * drops it when the dashboard loads.
+ */
+export declare const GroupByVariable: new (props: GroupByVariableProps) => VariableEntity<GroupByVariableProps>;
+/** An on/off switch, `$name` being `enabledValue` or `disabledValue`. New in Grafana 12.3. */
+export declare const SwitchVariable: new (props: SwitchVariableProps) => VariableEntity<SwitchVariableProps>;
 export declare function isVariableEntity(value: unknown): value is VariableEntity;
 export declare function isDatasourceVariable(value: unknown): value is DatasourceVariableEntity;
 /** Variable names Grafana defines itself; queries may use them without declaring anything. */

package/dist/variables.d.ts.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-grafana",
-  "version": "0.99.0",
+  "version": "0.100.0",
   "description": "Grafana lexicon for chant — typed dashboards, panels, queries and datasources, serialized to dashboard JSON and Grafana provisioning files",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -80,7 +80,7 @@
     "zod": "^4.3.6"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.99.0",
+    "@intentius/chant": "^0.100.0",
     "typescript": "^5.9.3",
     "zod": "^4.3.6"
   }

package/src/annotations.ts

@@ -0,0 +1,84 @@
+/**
+ * Dashboard annotations: the queries in a dashboard's `annotations.list`
+ * whose events Grafana draws on time series panels (deploy markers,
+ * incidents, alert state changes).
+ *
+ * An annotation is plain data on `Dashboard.annotations`, typed from
+ * Grafana's `AnnotationQuery`, except that its `datasource` takes the same
+ * values a panel's does (a `Datasource`, an `ExternalDatasource`, a
+ * `DatasourceVariable` or a `{ type, uid }` ref) and its `target` may be a
+ * query entity (`new PromQuery({ expr })`). What a datasource plugin keeps
+ * beside the common keys (Prometheus's legacy `expr`, `step`,
+ * `titleFormat`) is written as given.
+ *
+ * Grafana adds its built-in "Annotations & Alerts" query (`builtIn: 1`, the
+ * `-- Grafana --` datasource) to any dashboard without one, so a dashboard
+ * leaves it out unless it changes it (hides the toggle, turns it off).
+ */
+
+import type { AnnotationEventFieldMapping, AnnotationPanelFilter, AnnotationQuery, AnnotationQueryPlacement, DataSourceRef } from "./schema/dashboard.gen";
+import { isQueryEntity, type DatasourceInput, type QueryEntity } from "./query";
+import { compact } from "./util";
+
+/** One annotation query on a dashboard. */
+export interface AnnotationInput {
+  /** The name shown on its toggle, unique on the dashboard. */
+  name: string;
+  /** Where its events come from. Leave it out for Grafana's default datasource. */
+  datasource?: DatasourceInput;
+  /** Whether it runs when the dashboard loads. Defaults to true. */
+  enable?: boolean;
+  /** Hide its toggle in the dashboard's controls. */
+  hide?: boolean;
+  /** The colour of its markers. Defaults to `red`, as Grafana's editor does. */
+  iconColor?: string;
+  /** Only draw its events on these panels, or on every panel but these. */
+  filter?: AnnotationPanelFilter;
+  /** The query, in the datasource plugin's own shape, or a query entity of that plugin. */
+  target?: Record<string, unknown> | QueryEntity;
+  /** For the `-- Grafana --` datasource: `dashboard` or `tags`. */
+  type?: string;
+  /** 1 for Grafana's own "Annotations & Alerts" query. */
+  builtIn?: number;
+  placement?: AnnotationQueryPlacement;
+  /** Prometheus's legacy query fields, kept beside `target` by dashboards saved before Grafana 10. */
+  expr?: string;
+  textFormat?: string;
+  titleFormat?: string;
+  tagKeys?: string;
+  step?: string;
+  useValueForTime?: boolean;
+  /** How the fields of the query's result become an event's time, text and tags. */
+  mappings?: Record<string, AnnotationEventFieldMapping>;
+  /** Anything else a datasource plugin reads from its annotation query. */
+  [key: string]: unknown;
+}
+
+/** The refId Grafana gives an annotation query's target. */
+export const ANNOTATION_REF_ID = "Anno";
+
+/**
+ * One annotation as the entry Grafana stores in `annotations.list`.
+ * `datasourceRef` resolves the datasource the same way a panel's is (it is
+ * build.ts's, passed in so this module needs nothing from the build).
+ */
+export function annotationJson(input: AnnotationInput, datasourceRef: (d: DatasourceInput | undefined) => DataSourceRef | undefined): AnnotationQuery {
+  const { name, datasource, enable, iconColor, target, ...rest } = input;
+  let ds = datasourceRef(datasource);
+  let targetJson: Record<string, unknown> | undefined;
+  if (isQueryEntity(target)) {
+    const { datasource: queryDs, ...model } = target.props as Record<string, unknown> & { datasource?: DatasourceInput };
+    ds ??= datasourceRef(queryDs);
+    targetJson = compact({ refId: ANNOTATION_REF_ID, ...(target.queryDefinition.defaults ?? {}), ...model });
+  } else {
+    targetJson = target;
+  }
+  return compact({
+    ...(ds ? { datasource: ds } : {}),
+    enable: enable ?? true,
+    iconColor: iconColor ?? "red",
+    name,
+    ...rest,
+    ...(targetJson !== undefined ? { target: targetJson } : {}),
+  }) as AnnotationQuery;
+}

package/src/api/apply.test.ts

@@ -31,13 +31,31 @@ describe("planFromDashboards", () => {
       { json: dashboard("b", { __elements: { burn: LIB } }), folder: "Team A" },
       { json: dashboard("c") },
     ]);
-    expect(plan.folders).toEqual([{ uid: "team-a", title: "Team A" }]);
+    expect(plan.folders).toEqual([{ uid: "team-a", title: "Team A", path: "Team A" }]);
     expect(plan.libraryPanels).toEqual([{ uid: "burn", name: "Shared burn", model: LIB.model, folderUid: "team-a" }]);
     expect(plan.dashboards.map((d) => [d.uid, d.folderUid])).toEqual([["a", "team-a"], ["b", "team-a"], ["c", undefined]]);
     expect(Object.keys(plan.dashboards[0].json)).not.toEqual(expect.arrayContaining(["__elements"]));
     expect(planRefs(plan).map((r) => `${r.kind}/${r.name}`)).toEqual(["Folder/team-a", "LibraryPanel/burn", "Dashboard/a", "Dashboard/b", "Dashboard/c"]);
   });
 
+  test("a nested path is a folder per level, parents first; the build's folders pin uids (#2953)", () => {
+    const plan = planFromDashboards(
+      [
+        { json: dashboard("a"), folder: "Platform/Kubernetes" },
+        { json: dashboard("b"), folder: "Platform/Kubernetes/Nodes", folderUid: "nodes" },
+      ],
+      [{ uid: "plat", title: "Platform", path: "Platform" }, { uid: "empty", title: "Empty", path: "Empty" }],
+    );
+    expect(plan.folders).toEqual([
+      { uid: "empty", title: "Empty", path: "Empty" },
+      { uid: "plat", title: "Platform", path: "Platform" },
+      { uid: "platform-kubernetes", title: "Kubernetes", parentUid: "plat", path: "Platform/Kubernetes" },
+      { uid: "nodes", title: "Nodes", parentUid: "platform-kubernetes", path: "Platform/Kubernetes/Nodes" },
+    ]);
+    expect(plan.dashboards.map((d) => [d.uid, d.folderUid])).toEqual([["a", "platform-kubernetes"], ["b", "nodes"]]);
+    expect(() => planFromDashboards([{ json: dashboard("a"), folder: "X", folderUid: "one" }], [{ uid: "two", title: "X", path: "X" }])).toThrow(/declared with the uids/);
+  });
+
   test("a library variable in __elements is reported unsupported, not dropped", () => {
     const plan = planFromDashboards([{ json: dashboard("a", { __elements: { v: { uid: "v", name: "v", kind: 2, model: {} } } }) }]);
     expect(plan.unsupported).toEqual([expect.objectContaining({ kind: "LibraryElement", name: "v" })]);

package/src/api/apply.ts

@@ -51,8 +51,8 @@ import {
   ensureFolder,
   folderApi,
   folderContentCount,
-  foldersForDashboards,
   listFolders,
+  resolveFolders,
   send,
   type FolderPlan,
 } from "./folders";
@@ -92,10 +92,11 @@ export interface GrafanaApplyPlan {
   readonly unsupported: Array<{ kind: string; name: string; detail: string }>;
 }
 
-/** A dashboard as the build hands it over: its JSON and the folder title it names. */
+/** A dashboard as the build hands it over: its JSON, the folder path it names, and that folder's uid when the build resolved it. */
 export interface BuiltDashboardInput {
   readonly json: Json;
   readonly folder?: string;
+  readonly folderUid?: string;
 }
 
 function sameJson(a: unknown, b: unknown): boolean {
@@ -103,14 +104,23 @@ function sameJson(a: unknown, b: unknown): boolean {
 }
 
 /**
- * Turn built dashboards into an apply plan: the folders they name, the
+ * Turn built dashboards into an apply plan: the folders they name (each
+ * level of a path, with its parent) and the build's own `folders` (its
+ * index lists every one, `Folder`s holding no dashboard included), the
  * library panels their `__elements` carry, and the dashboards themselves.
  * Throws on a plan no apply could satisfy: a dashboard with no uid, two
- * dashboards with one uid, or one library panel uid with two models.
+ * dashboards with one uid, two folders with one uid, or one library panel
+ * uid with two models.
  */
-export function planFromDashboards(dashboards: readonly BuiltDashboardInput[]): GrafanaApplyPlan {
-  const folders = foldersForDashboards(dashboards);
-  const folderUid = new Map(folders.map((f) => [f.title, f.uid]));
+export function planFromDashboards(dashboards: readonly BuiltDashboardInput[], declaredFolders: readonly FolderPlan[] = []): GrafanaApplyPlan {
+  const resolved = resolveFolders({
+    declared: [
+      ...declaredFolders.flatMap((f) => (f.path ? [{ uid: f.uid, path: f.path }] : [])),
+      ...dashboards.flatMap((d) => (d.folder && d.folderUid ? [{ uid: d.folderUid, path: d.folder }] : [])),
+    ],
+    paths: dashboards.map((d) => d.folder),
+  });
+  const folders = resolved.folders;
   const libraryPanels = new Map<string, LibraryPanelPlan>();
   const unsupported: GrafanaApplyPlan["unsupported"] = [];
   const out: DashboardPlan[] = [];
@@ -120,7 +130,7 @@ export function planFromDashboards(dashboards: readonly BuiltDashboardInput[]):
     if (typeof uid !== "string" || uid === "") throw new Error(`grafana apply: dashboard "${String(d.json.title ?? "?")}" has no uid`);
     if (seen.has(uid)) throw new Error(`grafana apply: two dashboards have the uid "${uid}"`);
     seen.add(uid);
-    const inFolder = d.folder ? folderUid.get(d.folder) : undefined;
+    const inFolder = d.folderUid ?? resolved.uidOf(d.folder);
     const { panels, skipped } = libraryPanelsOf(d.json, inFolder);
     for (const p of panels) {
       const prior = libraryPanels.get(p.uid);

package/src/api/fake-grafana.ts

@@ -35,6 +35,8 @@ export interface FakeGrafanaState {
   dashboards: Record<string, FakeDashboard>;
   datasources?: Record<string, Json>;
   folders?: Record<string, string>;
+  /** A folder's parent uid, by folder uid, for nested folders. */
+  folderParents?: Record<string, string>;
   /** Answer every request with this status (a refused token: 401). */
   status?: number;
   namespace?: string;
@@ -147,8 +149,10 @@ export function fakeGrafana(state: FakeGrafanaState, calls: string[] = []): Graf
     }
     const folder = /^\/api\/folders\/([^/]+)$/.exec(route);
     if (folder) {
-      const title = state.folders?.[decodeURIComponent(folder[1])];
-      return title ? ok({ uid: folder[1], title }) : notFound;
+      const uid = decodeURIComponent(folder[1]);
+      const title = state.folders?.[uid];
+      const parentUid = state.folderParents?.[uid];
+      return title ? ok({ uid, title, ...(parentUid ? { parentUid } : {}) }) : notFound;
     }
     if (route === "/api/datasources") return ok(Object.values(state.datasources ?? {}).map(({ secureJsonFields: _s, ...rest }) => rest));
     const ds = /^\/api\/datasources\/uid\/([^/]+)$/.exec(route);