@intentius/chant-lexicon-grafana 0.99.0 → 0.100.0

package/README.md

@@ -21,12 +21,14 @@ export { prometheus, rate, requests, overview };
 |---|---|
 | dashboards | `Dashboard`, `Row`, `DashboardProvider` |
 | panels | `TimeSeriesPanel`, `StatPanel`, `GaugePanel`, `TablePanel`, `LogsPanel`, `TracesPanel`, `HeatmapPanel`, `TextPanel`, `BarChartPanel`, `BarGaugePanel`, `PieChartPanel`, `StateTimelinePanel`, `StatusHistoryPanel`, `HistogramPanel`, `NodeGraphPanel`, `XYChartPanel`, `TrendPanel`, `CanvasPanel`, `GeomapPanel`, `FlameGraphPanel`, `AlertListPanel` |
-| queries | `PromQuery` (PromQL), `TempoQuery` (TraceQL), `LokiQuery` (LogQL) |
-| variables | `QueryVariable`, `CustomVariable`, `IntervalVariable`, `DatasourceVariable`, `ConstantVariable`, `TextboxVariable` |
+| queries | `PromQuery` (PromQL), `TempoQuery` (TraceQL), `LokiQuery` (LogQL), `ElasticsearchQuery`, `CloudWatchQuery`, `AzureMonitorQuery`, `CloudMonitoringQuery`, `BigQueryQuery`, `PyroscopeQuery`, `PostgresQuery`, `MySQLQuery`, `MSSQLQuery` |
+| variables | `QueryVariable`, `CustomVariable`, `IntervalVariable`, `DatasourceVariable`, `ConstantVariable`, `TextboxVariable`, `AdhocVariable`, `GroupByVariable`, `SwitchVariable` |
 | datasources | `Datasource`, generic in its plugin type |
 | alerting | `AlertRuleGroup`, `AlertRule`, `AlertQuery`, the expressions `ReduceExpression`, `MathExpression`, `ThresholdExpression`, `ResampleExpression`, `ClassicConditionsExpression`, `SqlExpression`, and `ContactPoint`, `NotificationPolicy`, `MuteTiming`, `NotificationTemplate`, written to `provisioning/alerting/chant.yaml` |
 
-Panel options, field config and query fields are generated from Grafana's JSON Schemas as published by `grafana/grafana-foundation-sdk`, vendored in `src/spec/schemas/`, pinned by commit and digest in `GRAFANA_SCHEMA_PIN`, and corrected against Grafana's CUE by a checked-in overlay in `src/spec/overlay/`. They track Grafana 12.4 and 13.x. `definePanel` and `defineQuery` add plugins chant doesn't ship.
+Panel options, field config and query fields are generated from Grafana's JSON Schemas as published by `grafana/grafana-foundation-sdk`, vendored in `src/spec/schemas/`, pinned by commit and digest in `GRAFANA_SCHEMA_PIN`, and corrected against Grafana's CUE by a checked-in overlay in `src/spec/overlay/`. They track Grafana 12.4 and 13.x, and the tests validate real exports from Grafana 12.4.11 and 13.2.2. `definePanel` and `defineQuery` add plugins chant doesn't ship.
+
+Dashboards are written in the classic (v1) JSON model. Grafana 13's v2 model (tabs, auto grids, conditional rendering) cannot be declared yet. Import, drift and live export read a v2 dashboard by converting it to the classic model the way Grafana's own v1 read does, with a warning for each thing the conversion loses.
 
 ## Dashboards from other declarations
 
@@ -40,15 +42,19 @@ export const agents = AgentDashboard({ genAi: genAiMetrics(), datasource: promet
 
 ## Importing existing dashboards
 
-`chant import dashboard.json --output src` turns dashboard JSON exported from Grafana (with or without "Export for sharing externally") into this lexicon's TypeScript, in a directory named after the dashboard's uid: variables, one module per row with its panels and their queries, and the `Dashboard`. Panel ids, positions and refIds are kept, datasources named by uid become `ExternalDatasource`s, and `__inputs` datasources become `DatasourceVariable`s of the same name. A panel or datasource type chant has no class for is declared with `definePanel` or `defineQuery`. What the lexicon cannot express yet (annotations, library panels, ad hoc variables) is printed as a warning. A v2 dashboard is reported and not imported (#2947). `chant build` on the result gives back the same dashboard: the round-trip tests in `src/import/roundtrip.test.ts` hold Grafana 12.4.11 and 13.2.2 UI exports, community dashboards from grafana.com such as Node Exporter Full, and the examples' output to that. Datasource and dashboard provisioning files import too.
+`chant import dashboard.json --output src` turns dashboard JSON exported from Grafana (with or without "Export for sharing externally") into this lexicon's TypeScript, in a directory named after the dashboard's uid: variables, one module per row with its panels and their queries, and the `Dashboard`. Panel ids, positions and refIds are kept, datasources named by uid become `ExternalDatasource`s, and `__inputs` datasources become `DatasourceVariable`s of the same name. A panel or datasource type chant has no class for is declared with `definePanel` or `defineQuery`. What the lexicon cannot express yet (library panels, keys no prop takes) is printed as a warning. A v2 dashboard is converted to the classic model first, with a warning for each thing it loses. `chant build` on the result gives back the same dashboard: the round-trip tests in `src/import/roundtrip.test.ts` hold Grafana 12.4.11 and 13.2.2 UI exports, community dashboards from grafana.com such as Node Exporter Full, and the examples' output to that. Datasource and dashboard provisioning files import too.
 
 ## Drift and live export
 
 With `grafana.profiles.<env>` in `chant.config.ts` (a URL, and a service account token named by its environment variable), or `GRAFANA_URL` and `GRAFANA_TOKEN`, `chant lifecycle diff <env> --live` reads each declared dashboard and datasource from Grafana 12.4 or 13.x over `/apis/dashboard.grafana.app` (Grafana 11 over `/api/dashboards/uid`) and reports a dashboard edited in the UI as drift, at the path it was declared under (`panels[0].panels[1].title: Errors → 5xx`). The stored dashboard is read back through the importer, so what the build fills in (ids, grid positions, refIds) and what Grafana adds (the built-in annotation) is not reported. A dashboard is `owned` when one of the project's providers loaded it or its labels carry `app.kubernetes.io/managed-by: chant`. `chant import --from <env>` writes the environment's dashboards and datasources as TypeScript, through the same generator as `chant import`. The e2e in `src/observe.e2e.test.ts` runs both against Grafana 12.4.11 and 13.2.2.
 
+## Applying over the API
+
+`grafanaApply` writes a build to a running Grafana over its HTTP API instead of through provisioning files: folders, library panels an exported dashboard carries, and dashboards, labelled as the project's. With `prune` it deletes the project's dashboards and folders that the build no longer declares.
+
 ## Checks
 
-GRAF001 and GRAF002 run on source (uid and variable-name syntax, literal secrets). The GRAF1xx checks run after a build: undeclared or mistyped datasources, undeclared variables, duplicate uids and ids, panels off the grid or overlapping, uids Grafana rejects, validation against the pinned dashboard, panel and query schemas (an unknown key is a warning), a PromQL syntax check on every query sent to a Prometheus (GRAF108), dashboard providers that load a dashboard twice or not into its declared folder (GRAF109), and a check that every panel unit is one Grafana knows or a custom `suffix:`/`prefix:`-style unit (GRAF115).
+GRAF001 and GRAF002 run on source (uid and variable-name syntax, literal secrets). The GRAF1xx checks run after a build: undeclared or mistyped datasources, undeclared variables, duplicate uids and ids, panels off the grid or overlapping, uids Grafana rejects, validation against the pinned dashboard, panel and query schemas (an unknown key is a warning), a PromQL syntax check on every query sent to a Prometheus (GRAF108), dashboard providers that load a dashboard twice or not into its declared folder (GRAF109), a panel or row repeated over a variable that only ever holds one value (GRAF110), and a check that every panel unit is one Grafana knows or a custom `suffix:`/`prefix:`-style unit (GRAF115). For alerting: rules whose condition or expressions name no query (GRAF111), queries to undeclared datasources (GRAF112), routes to undeclared contact points or mute timings (GRAF113), and uids, intervals and duplicates Grafana refuses (GRAF114).
 
 GRAF101 and GRAF102 compare dashboards with the datasources declared in the same build root (chant #1939); keep them together, and declare a datasource that already exists in Grafana with `ExternalDatasource`, which the checks count and the build never provisions.
 
@@ -57,4 +63,4 @@ GRAF101 and GRAF102 compare dashboards with the datasources declared in the same
 - `buildGrafana(entities)` and `grafanaFiles(entities)` render every file by path, for embedding in another lexicon's output (a ConfigMap, a volume).
 - `GrafanaConfigMaps` and `grafanaVolumes` from `@intentius/chant-lexicon-grafana/k8s` deliver dashboards and provisioning to Kubernetes as ConfigMaps labelled for the Grafana Helm chart's sidecar (`grafana_dashboard`, `grafana_datasource`), or mounted into a plain Grafana Deployment.
 - `renderDashboard(dashboard)` and `dashboardJson(dashboard)` render one dashboard.
-- `validateGrafanaOutput({ dashboards, datasources })` and `validateDashboardSchema(json)` run the checks without a build.
+- `validateGrafanaOutput({ dashboards, datasources })` and `validateDashboardSchema(json)`, from `@intentius/chant-lexicon-grafana/validation`, run the checks without a build. They are not on the package root, so declaring dashboards does not load them; ajv loads the first time a schema is checked.

package/dist/annotations.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 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.js";
+import { type DatasourceInput, type QueryEntity } from "./query.js";
+/** 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 declare 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 declare function annotationJson(input: AnnotationInput, datasourceRef: (d: DatasourceInput | undefined) => DataSourceRef | undefined): AnnotationQuery;
+//# sourceMappingURL=annotations.d.ts.map

package/dist/annotations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotations.d.ts","sourceRoot":"","sources":["../src/annotations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,2BAA2B,EAAE,qBAAqB,EAAE,eAAe,EAAE,wBAAwB,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAC3J,OAAO,EAAiB,KAAK,eAAe,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAGhF,2CAA2C;AAC3C,MAAM,WAAW,eAAe;IAC9B,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,iFAAiF;IACjF,UAAU,CAAC,EAAE,eAAe,CAAC;IAC7B,kEAAkE;IAClE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,mDAAmD;IACnD,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,8EAA8E;IAC9E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yEAAyE;IACzE,MAAM,CAAC,EAAE,qBAAqB,CAAC;IAC/B,yFAAyF;IACzF,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,WAAW,CAAC;IAC/C,iEAAiE;IACjE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wDAAwD;IACxD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,wBAAwB,CAAC;IACrC,oGAAoG;IACpG,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,kFAAkF;IAClF,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,2BAA2B,CAAC,CAAC;IACvD,yEAAyE;IACzE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,4DAA4D;AAC5D,eAAO,MAAM,iBAAiB,SAAS,CAAC;AAExC;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,CAAC,CAAC,EAAE,eAAe,GAAG,SAAS,KAAK,aAAa,GAAG,SAAS,GAAG,eAAe,CAmBpJ"}

package/dist/api/apply.d.ts

@@ -72,18 +72,22 @@ export interface GrafanaApplyPlan {
         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;
 }
 /**
- * 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 declare function planFromDashboards(dashboards: readonly BuiltDashboardInput[]): GrafanaApplyPlan;
+export declare function planFromDashboards(dashboards: readonly BuiltDashboardInput[], declaredFolders?: readonly FolderPlan[]): GrafanaApplyPlan;
 /** Every resource in a plan, as `{ kind, name }`: what the result must account for. */
 export declare function planRefs(plan: GrafanaApplyPlan): Array<{
     kind: string;

package/dist/api/apply.d.ts.map

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

package/dist/api/fake-grafana.d.ts

@@ -31,6 +31,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;

package/dist/api/fake-grafana.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fake-grafana.d.ts","sourceRoot":"","sources":["../../src/api/fake-grafana.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAmB,MAAM,UAAU,CAAC;AAE7D,KAAK,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEpC,MAAM,WAAW,aAAa;IAC5B,6EAA6E;IAC7E,IAAI,EAAE,IAAI,CAAC;IACX,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,sGAAsG;IACtG,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,EAAE,CAAC,EAAE,IAAI,CAAC;IACV,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,4GAA4G;IAC5G,GAAG,EAAE,IAAI,GAAG,SAAS,GAAG,QAAQ,CAAC;IACjC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IAC1C,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,oEAAoE;IACpE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AA+BD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,IAAI,GAAG,IAAI,CAOjD;AAKD,mFAAmF;AACnF,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,EAAE,KAAK,GAAE,MAAM,EAAO,GAAG,WAAW,CAoEtF;AAED,4FAA4F;AAC5F,wBAAgB,cAAc,CAAC,EAAE,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,IAAI,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAsB/K"}
+{"version":3,"file":"fake-grafana.d.ts","sourceRoot":"","sources":["../../src/api/fake-grafana.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAmB,MAAM,UAAU,CAAC;AAE7D,KAAK,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEpC,MAAM,WAAW,aAAa;IAC5B,6EAA6E;IAC7E,IAAI,EAAE,IAAI,CAAC;IACX,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,sGAAsG;IACtG,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,EAAE,CAAC,EAAE,IAAI,CAAC;IACV,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,4GAA4G;IAC5G,GAAG,EAAE,IAAI,GAAG,SAAS,GAAG,QAAQ,CAAC;IACjC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IAC1C,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,gEAAgE;IAChE,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,oEAAoE;IACpE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AA+BD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,IAAI,GAAG,IAAI,CAOjD;AAKD,mFAAmF;AACnF,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,EAAE,KAAK,GAAE,MAAM,EAAO,GAAG,WAAW,CAsEtF;AAED,4FAA4F;AAC5F,wBAAgB,cAAc,CAAC,EAAE,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,IAAI,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAsB/K"}

package/dist/api/folders.d.ts

@@ -1,17 +1,19 @@
 /**
- * Folders, for the API applier (#2948). Every folder decision the applier
- * makes is in this module: which folders a build needs, the uid each gets,
- * how one is read, written, listed and deleted, and on which API.
+ * Folders: the one place a build's folders become uids and parents, and how
+ * the API applier (#2948) and observation read and write them.
  *
- * ## What the lexicon models today
+ * ## What a build declares
  *
- * A dashboard names its folder by title (`Dashboard.folder`), and a title
- * holds no nesting (the build flattens `/` in it). So the applier derives
- * one root-level folder per distinct title, with a stable uid made from the
- * title ({@link folderUidFor}), and a second apply finds it again by that
- * uid. {@link FolderPlan} already carries `parentUid`, and the writers
- * already send it, so #2953 (folder uid and nesting on the declaration) only
- * has to change {@link foldersForDashboards}.
+ * A dashboard names its folder as a path (`Dashboard.folder:
+ * "Platform/Kubernetes"`) or as a `Folder` (../folder.ts), and a `Folder`
+ * may be declared on its own. {@link resolveFolders} turns all of it into
+ * one {@link FolderPlan} per folder: every level of every path, the uid a
+ * `Folder` pins or {@link folderUidFor} of its path, and its parent's uid.
+ * The build calls it and writes the result to its index (`folders`, and a
+ * `folderUid` on each dashboard); the applier reads the index and calls it
+ * again, which also covers an index written before folders were listed.
+ * Two folders at one path with different uids, or two paths with one uid,
+ * throw: no delivery could make both.
  *
  * ## Which API
  *
@@ -24,6 +26,8 @@
  * there cannot be told apart from anyone else's, so it is never pruned.
  */
 import { type GrafanaClient } from "./client.js";
+import { folderUidFor } from "../folder.js";
+export { folderUidFor };
 export declare const FOLDER_GROUP = "folder.grafana.app";
 /** Folder API versions chant writes, newest first. */
 export declare const FOLDER_VERSIONS: readonly string[];
@@ -42,6 +46,8 @@ export interface FolderPlan {
     readonly title: string;
     /** The parent folder's uid; absent for a root-level folder. */
     readonly parentUid?: string;
+    /** Its titles from the root, joined with `/`: the directory file provisioning reads it from. */
+    readonly path?: string;
 }
 /** A folder as Grafana holds it. */
 export interface LiveFolder {
@@ -50,24 +56,48 @@ export interface LiveFolder {
     readonly parentUid?: string;
     /** `metadata.labels`; empty on the legacy API. */
     readonly labels: Readonly<Record<string, string>>;
+    /** `metadata.annotations`; empty on the legacy API. */
+    readonly annotations?: Readonly<Record<string, string>>;
     readonly via: "apis" | "legacy";
     /** The request path it lives at. */
     readonly address: string;
     /** The legacy folder's `version`, which its update needs. */
     readonly version?: number;
 }
+/** The folders a build resolves to, and the uid of each path. */
+export interface ResolvedFolders {
+    /** One per folder, sorted by path, so a parent comes before its children. */
+    readonly folders: FolderPlan[];
+    /** The uid of the folder at `path` (any spelling `folderLevels` reads the same); undefined for the General folder. */
+    uidOf(path: string | undefined): string | undefined;
+}
 /**
- * The uid chant gives the folder a dashboard names by title. Stable, so a
- * second apply finds the folder the first one made; Grafana's own limit is
- * 40 characters, which `slugUid` keeps to.
+ * Every folder a build needs, with its uid and parent: the folders declared
+ * with a uid (`Folder`s, or dashboards already resolved), and every level of
+ * every path a dashboard names. A level no declaration pins gets
+ * {@link folderUidFor} of its path. Throws when two declarations put
+ * different uids at one path, and when two paths would get one uid unless
+ * `duplicateUids` is `keep`: the build keeps both and GRAF104 reports them,
+ * since file provisioning, which gives folders uids of its own, can still
+ * deliver them.
  */
-export declare function folderUidFor(title: string): string;
+export declare function resolveFolders(input: {
+    declared?: Iterable<{
+        uid: string;
+        path: string;
+    }>;
+    paths?: Iterable<string | undefined>;
+}, options?: {
+    duplicateUids?: "throw" | "keep";
+}): ResolvedFolders;
 /**
- * The folders a set of dashboards needs, one per distinct title, sorted by
- * uid. The one place a dashboard's folder becomes a folder plan.
+ * The folders a set of dashboards needs: every level of every folder they
+ * name, sorted by path. A dashboard that already carries its `folderUid`
+ * pins its folder's uid.
  */
 export declare function foldersForDashboards(dashboards: Iterable<{
     folder?: string;
+    folderUid?: string;
 }>): FolderPlan[];
 /** The folder API the server behind `client` serves, discovered once per client. */
 export declare function folderApi(client: GrafanaClient): Promise<FolderApi>;
@@ -75,6 +105,12 @@ export declare function folderApi(client: GrafanaClient): Promise<FolderApi>;
 export declare function folderPath(api: FolderApi, namespace: string, uid: string): string;
 /** Read one folder; undefined when there is none with that uid. */
 export declare function readFolder(client: GrafanaClient, uid: string): Promise<LiveFolder | undefined>;
+/**
+ * The path of the folder with this uid, its titles from the root joined with
+ * `/`, the form `Dashboard.folder` takes. One read per folder per client;
+ * undefined when the folder, or one of its parents, cannot be found.
+ */
+export declare function liveFolderPath(client: GrafanaClient, uid: string): Promise<string | undefined>;
 /** Every folder in the organisation over `/apis`, paged. The legacy API has no labels to list by, so it is not listed. */
 export declare function listFolders(client: GrafanaClient): Promise<LiveFolder[]>;
 /** Send one write; throws {@link GrafanaApiError} on anything but a 2xx. */

package/dist/api/folders.d.ts.map

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

package/dist/build.d.ts

@@ -8,8 +8,9 @@
  * `buildGrafana()`.
  */
 import type { Declarable } from "@intentius/chant/declarable";
-import { type DatasourceEntity, type ExternalDatasourceEntity } from "./datasource.js";
-import { type DashboardEntity, type DashboardProviderProps } from "./dashboard.js";
+import { type DatasourceEntity, type DatasourceProvisioningProps, type DeletedDatasource, type ExternalDatasourceEntity } from "./datasource.js";
+import { type DashboardEntity, type DashboardProviderEntityProps } from "./dashboard.js";
+import { type FolderPlan } from "./api/folders.js";
 import { type PanelEntity, type RowEntity } from "./panels.js";
 import { type QueryEntity, type DatasourceInput } from "./query.js";
 import { type VariableEntity } from "./variables.js";
@@ -41,6 +42,11 @@ export interface ProvisionedDatasource {
     orgId?: number;
     version?: number;
 }
+/** The settings of the datasource provisioning file besides its datasources. */
+export interface DatasourceFileSettings {
+    prune: boolean;
+    deleteDatasources: DeletedDatasource[];
+}
 /** One entry of `providers:` in a dashboard provisioning file. */
 export interface ProvisionedProvider {
     name: string;
@@ -60,6 +66,8 @@ export interface BuiltDashboard {
     uid: string;
     title: string;
     folder?: string;
+    /** The uid of its folder, when it is in one. */
+    folderUid?: string;
     /** Path of its JSON file, relative to the output directory. */
     file: string;
     json: DashboardJson;
@@ -70,6 +78,10 @@ export interface BuiltGrafana {
     /** `ExternalDatasource` declarations: the checks count them, the provisioning file leaves them out. */
     externalDatasources: ExternalDatasourceRecord[];
     providers: ProvisionedProvider[];
+    /** Every folder the dashboards and `Folder`s name, each level of a path its own, sorted by path. */
+    folders: FolderPlan[];
+    /** `prune` and `deleteDatasources` of the datasource provisioning file. */
+    datasourceFile: DatasourceFileSettings;
     /** The alerting provisioning file, when the build declares any alerting. */
     alerting?: AlertingFile;
     /** Every output file by path, ready to write. */
@@ -83,8 +95,11 @@ export interface GrafanaIndex {
         uid: string;
         title: string;
         folder?: string;
+        folderUid?: string;
         file: string;
     }>;
+    /** The folders the dashboards are in, and any `Folder` declared: what the API applier creates, parents first. */
+    folders?: FolderPlan[];
     datasources: Array<{
         name: string;
         type: string;
@@ -132,9 +147,15 @@ export declare function provisionedDatasource(ds: DatasourceEntity): Provisioned
 /** One `ExternalDatasource` as the checks and the index see it. */
 export declare function externalDatasourceRecord(ds: ExternalDatasourceEntity): ExternalDatasourceRecord;
 /** One dashboard provider as a provisioning entry. */
-export declare function provisionedProvider(p: DashboardProviderProps): ProvisionedProvider;
-/** The datasource provisioning file for these datasources. */
-export declare function datasourcesYaml(datasources: ProvisionedDatasource[]): string;
+export declare function provisionedProvider(p: DashboardProviderEntityProps): ProvisionedProvider;
+/** `prune` and `deleteDatasources` as a build writes them: pruning on unless a `DatasourceProvisioning` turns it off. */
+export declare function datasourceFileSettings(props: DatasourceProvisioningProps | undefined): DatasourceFileSettings;
+/**
+ * The datasource provisioning file for these datasources. It prunes by
+ * default (`prune: true`), so a datasource removed from the build is removed
+ * from Grafana; `deleteDatasources` comes first, as Grafana runs it first.
+ */
+export declare function datasourcesYaml(datasources: ProvisionedDatasource[], settings?: DatasourceFileSettings): string;
 /** The dashboard provisioning file for these providers. */
 export declare function dashboardProvidersYaml(providers: ProvisionedProvider[]): string;
 /** Everything the grafana entities in a build render to. */

package/dist/build.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../src/build.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../src/build.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,EAKL,KAAK,gBAAgB,EACrB,KAAK,2BAA2B,EAEhC,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,EAC9B,MAAM,cAAc,CAAC;AACtB,OAAO,EAIL,KAAK,eAAe,EAEpB,KAAK,4BAA4B,EAClC,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAkB,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AAChE,OAAO,EAA8B,KAAK,WAAW,EAAE,KAAK,SAAS,EAAkB,MAAM,UAAU,CAAC;AACxG,OAAO,EAAiB,KAAK,WAAW,EAAE,KAAK,eAAe,EAAE,MAAM,SAAS,CAAC;AAChF,OAAO,EAA0C,KAAK,cAAc,EAAqB,MAAM,aAAa,CAAC;AAC7G,OAAO,KAAK,EACV,SAAS,IAAI,aAAa,EAE1B,aAAa,EAEb,KAAK,IAAI,SAAS,EAClB,QAAQ,IAAI,YAAY,EACxB,aAAa,EACd,MAAM,wBAAwB,CAAC;AAIhC,OAAO,EAA8C,KAAK,YAAY,EAAE,KAAK,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAGrH,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,CAAC;AAErF,yCAAyC;AACzC,eAAO,MAAM,YAAY,KAAK,CAAC;AAE/B,oEAAoE;AACpE,eAAO,MAAM,gBAAgB,wCAAwC,CAAC;AACtE,eAAO,MAAM,wBAAwB,uCAAuC,CAAC;AAC7E,eAAO,MAAM,cAAc,eAAe,CAAC;AAE3C,0DAA0D;AAC1D,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,gFAAgF;AAChF,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,OAAO,CAAC;IACf,iBAAiB,EAAE,iBAAiB,EAAE,CAAC;CACxC;AAED,kEAAkE;AAClE,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,EAAE,OAAO,CAAC;IACzB,cAAc,EAAE,OAAO,CAAC;IACxB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,yBAAyB,EAAE,OAAO,CAAA;KAAE,CAAC;CAC/D;AAED,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,aAAa,CAAC;CACrB;AAED,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,cAAc,EAAE,CAAC;IAC7B,WAAW,EAAE,qBAAqB,EAAE,CAAC;IACrC,uGAAuG;IACvG,mBAAmB,EAAE,wBAAwB,EAAE,CAAC;IAChD,SAAS,EAAE,mBAAmB,EAAE,CAAC;IACjC,oGAAoG;IACpG,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,2EAA2E;IAC3E,cAAc,EAAE,sBAAsB,CAAC;IACvC,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,0EAA0E;IAC1E,KAAK,EAAE,YAAY,CAAC;CACrB;AAED,MAAM,WAAW,YAAY;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACrG,iHAAiH;IACjH,OAAO,CAAC,EAAE,UAAU,EAAE,CAAC;IACvB,WAAW,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAChE,qFAAqF;IACrF,mBAAmB,CAAC,EAAE,wBAAwB,EAAE,CAAC;IACjD,sGAAsG;IACtG,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,kEAAkE;AAClE,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAcD,mHAAmH;AACnH,wBAAgB,aAAa,CAAC,KAAK,EAAE,eAAe,GAAG,SAAS,GAAG,aAAa,GAAG,SAAS,CAM3F;AAoCD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAM3F;AAOD,yDAAyD;AACzD,wBAAgB,aAAa,CAAC,QAAQ,EAAE,cAAc,GAAG,aAAa,CAiHrE;AAqBD,mCAAmC;AACnC,wBAAgB,UAAU,CAAC,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAUtH;AA2KD,yEAAyE;AACzE,wBAAgB,UAAU,CAAC,KAAK,EAAE,KAAK,CAAC,WAAW,GAAG,SAAS,CAAC,GAAG,KAAK,CAAC,SAAS,GAAG,YAAY,CAAC,CA4CjG;AAMD,oFAAoF;AACpF,wBAAgB,YAAY,CAAC,SAAS,EAAE,eAAe,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAEpF;AAED,iDAAiD;AACjD,wBAAgB,eAAe,CAAC,SAAS,EAAE,eAAe,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,aAAa,CAsB9F;AAED,4CAA4C;AAC5C,wBAAgB,aAAa,CAAC,SAAS,EAAE,eAAe,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAErF;AAcD,8CAA8C;AAC9C,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,gBAAgB,GAAG,qBAAqB,CAoBjF;AAED,mEAAmE;AACnE,wBAAgB,wBAAwB,CAAC,EAAE,EAAE,wBAAwB,GAAG,wBAAwB,CAE/F;AAED,sDAAsD;AACtD,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,4BAA4B,GAAG,mBAAmB,CAgBxF;AAMD,yHAAyH;AACzH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,2BAA2B,GAAG,SAAS,GAAG,sBAAsB,CAK7G;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,qBAAqB,EAAE,EAAE,QAAQ,GAAE,sBAA0D,GAAG,MAAM,CAOlJ;AAED,2DAA2D;AAC3D,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,mBAAmB,EAAE,GAAG,MAAM,CAE/E;AAoBD,4DAA4D;AAC5D,wBAAgB,YAAY,CAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,QAAQ,CAAC,UAAU,CAAC,GAAG,YAAY,CAqEnG;AAED,2FAA2F;AAC3F,wBAAgB,YAAY,CAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,QAAQ,CAAC,UAAU,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAE7G"}

package/dist/catalog.d.ts

@@ -4,7 +4,7 @@
  * completions and hover, and the docs.
  */
 import type { LexiconEntry } from "@intentius/chant/lsp/lexicon-providers";
-export type CatalogKind = "dashboard" | "datasource" | "provider" | "panel" | "row" | "query" | "variable" | "alerting" | "expression";
+export type CatalogKind = "dashboard" | "folder" | "datasource" | "provider" | "panel" | "row" | "query" | "variable" | "alerting" | "expression";
 export interface CatalogEntry {
     className: string;
     entityType: string;

package/dist/catalog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wCAAwC,CAAC;AAiB3E,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,YAAY,GAAG,UAAU,GAAG,OAAO,GAAG,KAAK,GAAG,OAAO,GAAG,UAAU,GAAG,UAAU,GAAG,YAAY,CAAC;AAEvI,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,WAAW,CAAC;IAClB,wEAAwE;IACxE,UAAU,EAAE,UAAU,GAAG,UAAU,CAAC;IACpC,qDAAqD;IACrD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB;AA8CD,eAAO,MAAM,eAAe,EAAE,YAAY,EAyGzC,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAM9D"}
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wCAAwC,CAAC;AAkB3E,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,QAAQ,GAAG,YAAY,GAAG,UAAU,GAAG,OAAO,GAAG,KAAK,GAAG,OAAO,GAAG,UAAU,GAAG,UAAU,GAAG,YAAY,CAAC;AAElJ,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,WAAW,CAAC;IAClB,wEAAwE;IACxE,UAAU,EAAE,UAAU,GAAG,UAAU,CAAC;IACpC,qDAAqD;IACrD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB;AAiDD,eAAO,MAAM,eAAe,EAAE,YAAY,EAuHzC,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAM9D"}

package/dist/codegen/docs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../src/codegen/docs.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAuGH,wBAAsB,YAAY,CAAC,IAAI,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAuB9E"}
+{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../src/codegen/docs.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA8GH,wBAAsB,YAAY,CAAC,IAAI,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAuB9E"}

package/dist/codegen/generate.d.ts

@@ -4,12 +4,18 @@
  * 1. `src/schema/<name>.gen.ts` from each vendored schema in `src/spec/schemas/`
  *    (see `src/pin.ts`). These are committed, and a test fails when they
  *    drift from what this step would write.
- * 2. `src/generated/lexicon-grafana.json`, the registry of entity classes
+ * 2. `src/spec/schemas.gen.ts`, the same schemas with the overlay applied, as
+ *    JSON text. Validation (GRAF107, the `/validation` subpath) reads them
+ *    from there rather than from the files, so it needs no filesystem access
+ *    and works bundled. Committed and checked the same way.
+ * 3. `src/generated/lexicon-grafana.json`, the registry of entity classes
  *    the package exports, derived from the catalog so the packaged
  *    `dist/meta.json` cannot disagree with the classes.
  */
 import type { GenerateResult } from "@intentius/chant/codegen/generate";
 export type { GenerateResult };
+/** `src/spec/schemas.gen.ts`: each schema validation uses, overlay applied, as one line of JSON text. */
+export declare function schemaDataModule(): string;
 /** Every generated schema module, keyed by path relative to the package root. */
 export declare function schemaModules(): Record<string, string>;
 export declare function generate(opts?: {

package/dist/codegen/generate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../src/codegen/generate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AAKxE,YAAY,EAAE,cAAc,EAAE,CAAC;AAY/B,iFAAiF;AACjF,wBAAgB,aAAa,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAQtD;AAQD,wBAAsB,QAAQ,CAAC,IAAI,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,cAAc,CAAC,CA2BrG;AAED,mGAAmG;AACnG,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAIhE"}
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../src/codegen/generate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AAKxE,YAAY,EAAE,cAAc,EAAE,CAAC;AAY/B,yGAAyG;AACzG,wBAAgB,gBAAgB,IAAI,MAAM,CAkBzC;AAED,iFAAiF;AACjF,wBAAgB,aAAa,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAStD;AAQD,wBAAsB,QAAQ,CAAC,IAAI,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,cAAc,CAAC,CA2BrG;AAED,mGAAmG;AACnG,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAIhE"}

package/dist/composites/shared.d.ts

@@ -4,6 +4,7 @@
  */
 import type { DatasourceInput } from "../query.js";
 import type { DashboardLinkInput } from "../dashboard.js";
+import type { FolderEntity } from "../folder.js";
 import type { ThresholdsConfig } from "../schema/dashboard.gen.js";
 /** Dashboard settings every composite takes; each has a default derived from what it reads. */
 export interface DashboardOptions {
@@ -14,8 +15,8 @@ export interface DashboardOptions {
     uid?: string;
     description?: string;
     tags?: string[];
-    /** The Grafana folder to provision it into. */
-    folder?: string;
+    /** The Grafana folder to provision it into: a path, or a `Folder` to pin its uid. */
+    folder?: string | FolderEntity;
     /** Initial time range. */
     time?: {
         from: string;
@@ -58,7 +59,7 @@ export declare function dashboardProps(o: DashboardOptions, defaults: {
     tags: string[];
 }): {
     links?: DashboardLinkInput[] | undefined;
-    folder?: string | undefined;
+    folder?: string | FolderEntity | undefined;
     graphTooltip: "sharedCrosshair";
     refresh: string;
     title: string;

package/dist/composites/shared.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../src/composites/shared.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAChD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEhE,+FAA+F;AAC/F,MAAM,WAAW,gBAAgB;IAC/B,yIAAyI;IACzI,UAAU,EAAE,eAAe,CAAC,YAAY,CAAC,CAAC;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8EAA8E;IAC9E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,+CAA+C;IAC/C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0BAA0B;IAC1B,IAAI,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;IACpC,yCAAyC;IACzC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,kBAAkB,EAAE,CAAC;CAC9B;AAED,6CAA6C;AAC7C,MAAM,MAAM,OAAO,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,GAAG,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;AAEnF,+DAA+D;AAC/D,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,MAAM,CAGpE;AAED,2EAA2E;AAC3E,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,KAAK,SAAqB,GAAG,MAAM,CAErF;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,MAAM,CAGjF;AAED,0EAA0E;AAC1E,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,MAAM,CAE3E;AAED,+EAA+E;AAC/E,wBAAgB,GAAG,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAErC;AAED,yCAAyC;AACzC,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED,wDAAwD;AACxD,wBAAgB,MAAM,CAAC,GAAG,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAElD;AAED,wEAAwE;AACxE,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAE7D;AAED,0EAA0E;AAC1E,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,gBAAgB,CAEzF;AAED,0FAA0F;AAC1F,wBAAgB,cAAc,CAAC,CAAC,EAAE,gBAAgB,EAAE,QAAQ,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE;;;;;;;;;;cA9DhH,MAAM;YAAM,MAAM;;EA0ElC;AAED,uDAAuD;AACvD,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,GAAG,IAAI,CAMtE"}
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../src/composites/shared.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAChD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEhE,+FAA+F;AAC/F,MAAM,WAAW,gBAAgB;IAC/B,yIAAyI;IACzI,UAAU,EAAE,eAAe,CAAC,YAAY,CAAC,CAAC;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8EAA8E;IAC9E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,qFAAqF;IACrF,MAAM,CAAC,EAAE,MAAM,GAAG,YAAY,CAAC;IAC/B,0BAA0B;IAC1B,IAAI,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;IACpC,yCAAyC;IACzC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,kBAAkB,EAAE,CAAC;CAC9B;AAED,6CAA6C;AAC7C,MAAM,MAAM,OAAO,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,GAAG,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;AAEnF,+DAA+D;AAC/D,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,MAAM,CAGpE;AAED,2EAA2E;AAC3E,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,KAAK,SAAqB,GAAG,MAAM,CAErF;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,MAAM,CAGjF;AAED,0EAA0E;AAC1E,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,MAAM,CAE3E;AAED,+EAA+E;AAC/E,wBAAgB,GAAG,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAErC;AAED,yCAAyC;AACzC,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED,wDAAwD;AACxD,wBAAgB,MAAM,CAAC,GAAG,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAElD;AAED,wEAAwE;AACxE,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAE7D;AAED,0EAA0E;AAC1E,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,gBAAgB,CAEzF;AAED,0FAA0F;AAC1F,wBAAgB,cAAc,CAAC,CAAC,EAAE,gBAAgB,EAAE,QAAQ,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE;;;;;;;;;;cA9DhH,MAAM;YAAM,MAAM;;EA0ElC;AAED,uDAAuD;AACvD,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,GAAG,IAAI,CAMtE"}

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 {
@@ -51,20 +53,39 @@ export interface DashboardProps {
     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`). `"Platform/Kubernetes"` nests one
-     * directory in another, which Grafana 13.1 and later make a Kubernetes
-     * folder inside Platform; earlier versions use only the last level
-     * (GRAF109 warns). 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. */
@@ -74,11 +95,14 @@ export interface DashboardProviderProps {
     name: string;
     orgId?: number;
     /**
-     * Put every dashboard this provider loads in this folder. Setting it (or
-     * `folderUid`) turns `foldersFromFilesStructure` off by default, so each
-     * dashboard's own `folder` is ignored (GRAF109 warns).
+     * 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;
+    folder?: string | FolderEntity;
     folderUid?: string;
     /** Where the `dashboards/` output is mounted in the Grafana container. Defaults to `/var/lib/grafana/dashboards`. */
     path?: string;
@@ -88,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. */