@intentius/chant-lexicon-grafana 0.98.0 → 0.100.0

package/dist/skills/chant-grafana.md

@@ -26,11 +26,11 @@ const tempo = new Datasource({ name: "Tempo", type: "tempo", url: "http://tempo:
 export { prometheus, tempo };
 ```
 
-The uid defaults to the name as a uid (`prometheus`, `tempo`). Secrets go in `secureJsonData` as `"$__env{NAME}"` or `"$__file{/path}"`, never literally (GRAF002). A declared `Datasource` inside `jsonData` is written as its uid, which is how a Tempo datasource links to Loki or Prometheus.
+The uid defaults to the name as a uid (`prometheus`, `tempo`). Secrets go in `secureJsonData` as `"$__env{NAME}"` or `"$__file{/path}"`, never literally (GRAF002). `jsonData` and the `secureJsonData` keys are typed per plugin for every plugin with a query class. A declared `Datasource` inside `jsonData` is written as its uid, which is how a Tempo datasource links to Loki or Prometheus and a Prometheus exemplar to Tempo; a link field only takes a datasource of a type Grafana offers there.
 
 ## Queries
 
-`PromQuery` (PromQL in `expr`), `TempoQuery` (TraceQL in `query`) and `LokiQuery` (LogQL in `expr`). Fields are typed from Grafana's own query schemas. `datasource` only accepts a datasource of the query's plugin type, so a PromQL query can't be pointed at Tempo.
+`PromQuery` (PromQL in `expr`), `TempoQuery` (TraceQL in `query`), `LokiQuery` (LogQL in `expr`), `ElasticsearchQuery`, `CloudWatchQuery`, `AzureMonitorQuery`, `CloudMonitoringQuery`, `BigQueryQuery`, `PyroscopeQuery`, and `PostgresQuery`, `MySQLQuery` and `MSSQLQuery` (SQL in `rawSql`). Fields are typed from Grafana's own query schemas, or by hand for SQL. `datasource` only accepts a datasource of the query's plugin type, so a PromQL query can't be pointed at Tempo.
 
 ```ts
 const requestRate = new PromQuery({
@@ -41,7 +41,7 @@ const requestRate = new PromQuery({
 
 ## Panels and dashboards
 
-Panel classes: `TimeSeriesPanel`, `StatPanel`, `GaugePanel`, `TablePanel`, `LogsPanel`, `TracesPanel`, `HeatmapPanel`, `TextPanel`, plus `Row`. `options` and `fieldConfig.defaults.custom` are typed from each panel's schema, and every option is optional because Grafana fills in the rest.
+Panel classes: `TimeSeriesPanel`, `StatPanel`, `GaugePanel`, `TablePanel`, `LogsPanel`, `TracesPanel`, `HeatmapPanel`, `TextPanel`, `BarChartPanel`, `BarGaugePanel`, `PieChartPanel`, `StateTimelinePanel`, `StatusHistoryPanel`, `HistogramPanel`, `NodeGraphPanel`, `XYChartPanel`, `TrendPanel`, `CanvasPanel`, `GeomapPanel`, `FlameGraphPanel`, `AlertListPanel`, plus `Row`. `options` and `fieldConfig.defaults.custom` are typed from each panel's schema, and every option is optional because Grafana fills in the rest.
 
 ```ts
 const rate = new TimeSeriesPanel({ title: "Request rate", datasource: prometheus, targets: [requestRate] });
@@ -55,9 +55,11 @@ export const overview = new Dashboard({
 });
 ```
 
-Leave `gridPos` out and panels are placed left to right, wrapping at 24 columns; give `x` and `y` to place one exactly. `Row({ title, panels, collapsed })` starts a full-width row. Dashboard uids default to the export name as a uid (`overview`).
+`transformations` is typed per transformer id, from Grafana v13.2.2's transformers: `transformation("organize", { excludeByName: { Time: true } })` checks the options against that one transformer, and a `{ id, options }` literal works too. Use `customTransformation(id, options)` for a plugin's transformer or options the types don't have.
 
-chant's lint wants flat declarations: extract nested objects (`time`, `options`) to named consts, keep at most eight declarations per file, and export entities with `export { a, b }`.
+Leave `gridPos` out and panels are placed left to right, wrapping at 24 columns and flowing around explicitly placed panels; give `x` and `y` to place one exactly. `Row({ title, panels, collapsed })` starts a full-width row. Dashboard uids default to the export name as a uid (`overview`).
+
+Panels, rows, queries and variables are property-kind, so chant's core lint doesn't count them toward the eight-per-file limit (COR009) and lets them carry `fieldConfig` and `options` inline (COR001). The dashboard is a resource: lift its own nested objects (`time`, `links`) into named consts.
 
 ## Dashboards built from other declarations
 
@@ -75,18 +77,23 @@ const agents = AgentDashboard({ genAi: genai, datasource: prometheus });
 export { services, checkoutSlo, agents };
 ```
 
-Pass the `prometheus` exporter as `exporter` to `RedDashboard` when its `namespace` changes the names. `datasource` may be a `{ type: "prometheus", uid }` ref to a datasource declared elsewhere. Never hand-write the span-metric or SLO series names in a query next to these; use `spanMetricsNames()` (otel), `sloMetrics()` (prometheus) or `genAiMetrics()` (otel), or the composites' `redQueries`, `sloQueries` and `agentQueries`.
+Pass the `prometheus` exporter as `exporter` to `RedDashboard` when its `namespace` changes the names. `RedDashboard` counts server and consumer spans only; pass `spanKinds` to count others, or `[]` for every kind. `datasource` may be a `{ type: "prometheus", uid }` ref to a datasource declared elsewhere. Never hand-write the span-metric or SLO series names in a query next to these; use `spanMetricsNames()` (otel), `sloMetrics()` (prometheus) or `genAiMetrics()` (otel), or the composites' `redQueries`, `sloQueries` and `agentQueries`.
 
 ## Rules
 
-- GRAF101: every panel, query and query variable names a declared datasource. GRAF102: of the right type.
+- GRAF101: every panel, query, and query, ad hoc and group by variable names a declared datasource (`Datasource` or `ExternalDatasource`), and every datasource variable's plugin type has one. GRAF102: of the right type.
 - GRAF103: every `$name`/`${name}` in a query, title or repeat is a declared variable (`$__*` are Grafana's own).
 - GRAF104: unique dashboard uids, datasource uids and names, panel ids, variable names and refIds.
 - GRAF105: panels fit the 24-column grid and don't overlap.
 - GRAF106: uids of 1-40 letters, digits, `-`, `_`; dashboards have titles.
 - GRAF107: the dashboard matches Grafana's schema at the pinned version.
+- GRAF108: every query and query variable sent to a Prometheus parses as PromQL (template variables and `$__` macros are substituted first; an object-form variable query is checked on its `query`).
+- GRAF109: the dashboard providers put each dashboard in its declared folder, and no two load the same files.
+- GRAF110: a panel or row repeats over a query, custom or datasource variable with `multi` or `includeAll`, or a group by variable; anything else shows it once (warning).
+- GRAF115 (warning): every panel unit is a Grafana unit id (`bytes`, `s`, `percent`, `reqps`, ...) or a custom unit (`suffix: cores`, `prefix:$`, `si:mF`, `count:reqs`, `currency:EUR`). Grafana shows anything else as literal text after the value.
+- GRAF111-GRAF114: alert rules, contact points, policies and mute timings; see the chant-grafana-alerting skill.
 
-GRAF101 and GRAF102 compare against the datasources in the same build root, so keep datasources and dashboards in one `chant build` (chant #1939).
+GRAF101 and GRAF102 compare against the datasources in the same build root, so keep datasources and dashboards in one `chant build` (chant #1939). For a datasource that exists in Grafana but is provisioned elsewhere, declare `new ExternalDatasource({ type: "prometheus", uid: "mimir" })` and use it like a `Datasource`; it is checked against, never provisioned.
 
 ## Other plugins
 

package/dist/spec/fetch-units-cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env tsx
+export {};
+//# sourceMappingURL=fetch-units-cli.d.ts.map

package/dist/spec/fetch-units-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-units-cli.d.ts","sourceRoot":"","sources":["../../src/spec/fetch-units-cli.ts"],"names":[],"mappings":""}

package/dist/spec/overlay.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The correction overlay: checked-in patches applied to the vendored schemas
+ * before type generation and validation.
+ *
+ * The vendored foundation-sdk schemas are stricter than Grafana's own CUE
+ * (`additionalProperties: false` everywhere, `options` typed as a record
+ * where the CUE says `_`, fields required that the CUE defaults) and lag it
+ * (no `MatcherConfig.scope`). Each `src/spec/overlay/<name>.overlay.json`
+ * lists patches for one schema. A patch is a small JSON-patch operation
+ * (`add`, `replace` or `remove`, RFC 6902 paths) and cites the Grafana
+ * source line it follows, so every correction is traceable and can be
+ * dropped when the pin catches up.
+ *
+ * Applying is strict: `add` refuses a key that is already there and
+ * `replace`/`remove` refuse a path that is not, so bumping the pin to a
+ * schema that already carries a fix fails `npm run generate` until the
+ * patch is removed.
+ */
+import type { SchemaName } from "../pin.js";
+export interface OverlayPatch {
+    op: "add" | "replace" | "remove";
+    /** JSON pointer into the vendored schema. */
+    path: string;
+    value?: unknown;
+    /** The Grafana source this follows: `<repo path>:<line>` at the tag named in the file. */
+    source: string;
+    /** Why the vendored schema is wrong here. */
+    why: string;
+}
+export interface SchemaOverlay {
+    $comment?: string;
+    schema: SchemaName;
+    /** The Grafana tag(s) the `source` lines refer to. */
+    grafana: string;
+    patches: OverlayPatch[];
+}
+export declare function overlayDir(): string;
+export declare function overlayPath(name: SchemaName): string;
+/** The overlay for one schema, or undefined when it has none. */
+export declare function loadOverlay(name: SchemaName): SchemaOverlay | undefined;
+/** A copy of `schema` with every patch applied, in order. */
+export declare function applyOverlay(schema: Record<string, unknown>, overlay: SchemaOverlay): Record<string, unknown>;
+//# sourceMappingURL=overlay.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"overlay.d.ts","sourceRoot":"","sources":["../../src/spec/overlay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAEzC,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,KAAK,GAAG,SAAS,GAAG,QAAQ,CAAC;IACjC,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,0FAA0F;IAC1F,MAAM,EAAE,MAAM,CAAC;IACf,6CAA6C;IAC7C,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,UAAU,CAAC;IACnB,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,YAAY,EAAE,CAAC;CACzB;AAED,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAEpD;AAED,iEAAiE;AACjE,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,aAAa,GAAG,SAAS,CAMvE;AAUD,6DAA6D;AAC7D,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAmC7G"}

package/dist/spec/schemas.d.ts

@@ -1,24 +1,32 @@
 /**
- * Read the vendored Grafana schemas (`src/spec/schemas/*.jsonschema.json`) and check
- * them against the digests in `GRAFANA_SCHEMA_PIN`.
- */
-import { type SchemaName } 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.
+ * 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/`. */
 export declare function schemasDir(): string;
-export declare function schemaPath(name: SchemaName): string;
+export declare function schemaPath(name: VendoredSchemaName): string;
 export declare function sha256(text: string | Buffer): string;
 /** The raw bytes of one vendored schema. */
-export declare function readSchemaText(name: SchemaName): string;
-/** One vendored schema, parsed (cached per process). */
+export declare function readSchemaText(name: VendoredSchemaName): string;
+/** One vendored schema exactly as pinned, parsed, without the overlay. */
+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). 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. */
 export declare function digestMismatches(): Array<{
-    name: SchemaName;
+    name: VendoredSchemaName;
     expected: string;
     actual: string;
 }>;

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

@@ -1 +1 @@
-{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../src/spec/schemas.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,OAAO,EAAoC,KAAK,UAAU,EAAE,MAAM,QAAQ,CAAC;AAE3E;;;;;GAKG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAEnD;AAED,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAEpD;AAED,4CAA4C;AAC5C,wBAAgB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAEvD;AAID,wDAAwD;AACxD,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAOpE;AAED,+EAA+E;AAC/E,wBAAgB,gBAAgB,IAAI,KAAK,CAAC;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAQhG"}
+{"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/spec/units.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The units Grafana knows, for GRAF115.
+ *
+ * A field's `unit` is a free string in the dashboard schema. Grafana looks it
+ * up in its value-format registry (`getValueFormat()` in
+ * `packages/grafana-data/src/valueFormats/valueFormats.ts`): a registered id
+ * formats the value, `<kind>:<arg>` builds a custom unit, and anything else is
+ * shown after the value as a literal suffix. So `"byte"` renders `5 byte`
+ * where `"bytes"` would render `5 B`, and nothing complains.
+ *
+ * The ids in `units.gen.ts` are taken from the registry at
+ * `GRAFANA_UNITS_SOURCE` by `just fetch-units`.
+ */
+import { GRAFANA_UNIT_IDS } from "./units.gen.js";
+export declare const GRAFANA_UNITS_SOURCE: Readonly<{
+    repo: "grafana/grafana";
+    ref: "v13.2.2";
+    commit: "3db12332b66497c31f8ad2a5fb0eb0fe0ca05a7e";
+    path: "packages/grafana-data/src/valueFormats/categories.ts";
+}>;
+/** Old ids `buildFormats()` in valueFormats.ts still resolves (v13.2.2). */
+export declare const LEGACY_UNIT_ALIASES: readonly string[];
+/**
+ * The `<kind>:` prefixes `getValueFormat()` turns into a custom unit
+ * (v13.2.2): `prefix:$`, `suffix: req`, `time:YYYY-MM-DD`, `si:mF`,
+ * `count:reqs`, `currency:€` (or `currency:financial:€[:suffix]`) and
+ * `bool:yes/no`.
+ */
+export declare const CUSTOM_UNIT_KINDS: readonly string[];
+export { GRAFANA_UNIT_IDS };
+/** Whether Grafana formats `unit` as a unit rather than showing it as a literal suffix. An empty unit means none. */
+export declare function isGrafanaUnit(unit: string): boolean;
+/** The registered id `unit` most likely meant: same letters in another case, or one or two edits away. */
+export declare function closestGrafanaUnit(unit: string): string | undefined;
+//# sourceMappingURL=units.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"units.d.ts","sourceRoot":"","sources":["../../src/spec/units.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C,eAAO,MAAM,oBAAoB;;;;;EAK/B,CAAC;AAEH,4EAA4E;AAC5E,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAAkB,CAAC;AAEpE;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,EAAE,SAAS,MAAM,EAAoE,CAAC;AAIpH,OAAO,EAAE,gBAAgB,EAAE,CAAC;AAE5B,qHAAqH;AACrH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAInD;AAgBD,0GAA0G;AAC1G,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAgBnE"}

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

@@ -0,0 +1,2 @@
+export declare const GRAFANA_UNIT_IDS: readonly string[];
+//# sourceMappingURL=units.gen.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"units.gen.d.ts","sourceRoot":"","sources":["../../src/spec/units.gen.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,gBAAgB,EAAE,SAAS,MAAM,EAmR7C,CAAC"}