@intentius/chant-lexicon-grafana 0.124.30 → 0.124.32

package/dist/validate.js

@@ -0,0 +1,122 @@
+/**
+ * Validate the grafana lexicon's own artifacts: the vendored schemas match
+ * their pinned digests, the committed schema types match what generate would
+ * write, every required class is in the registry, and every built-in panel
+ * renders to a dashboard the pinned schema accepts.
+ */
+import { readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { BUILTIN_CATALOG, lexiconRegistry } from "./catalog.js";
+import { digestMismatches } from "./spec/schemas.js";
+import { schemaModules } from "./codegen/generate.js";
+import * as panels from "./panels.js";
+import { Dashboard } from "./dashboard.js";
+import { renderDashboard } from "./build.js";
+import { validateDashboardSchema } from "./schema-validate.js";
+/** Every entity class the package must keep exporting. */
+export const REQUIRED_NAMES = [
+    "Dashboard",
+    "Datasource",
+    "ExternalDatasource",
+    "DashboardProvider",
+    "DatasourceProvisioning",
+    "Folder",
+    "LibraryPanel",
+    "LibraryPanelRef",
+    "Row",
+    "TimeSeriesPanel",
+    "StatPanel",
+    "GaugePanel",
+    "TablePanel",
+    "LogsPanel",
+    "TracesPanel",
+    "HeatmapPanel",
+    "TextPanel",
+    "BarChartPanel",
+    "BarGaugePanel",
+    "PieChartPanel",
+    "StateTimelinePanel",
+    "StatusHistoryPanel",
+    "HistogramPanel",
+    "NodeGraphPanel",
+    "XYChartPanel",
+    "TrendPanel",
+    "CanvasPanel",
+    "GeomapPanel",
+    "CandlestickPanel",
+    "AnnotationsListPanel",
+    "DashboardListPanel",
+    "NewsPanel",
+    "DataGridPanel",
+    "FlameGraphPanel",
+    "AlertListPanel",
+    "PromQuery",
+    "TempoQuery",
+    "LokiQuery",
+    "ElasticsearchQuery",
+    "CloudWatchQuery",
+    "AzureMonitorQuery",
+    "CloudMonitoringQuery",
+    "BigQueryQuery",
+    "PyroscopeQuery",
+    "OpenSearchQuery",
+    "PostgresQuery",
+    "MySQLQuery",
+    "MSSQLQuery",
+    "QueryVariable",
+    "CustomVariable",
+    "IntervalVariable",
+    "DatasourceVariable",
+    "ConstantVariable",
+    "TextboxVariable",
+    "AdhocVariable",
+    "GroupByVariable",
+    "SwitchVariable",
+];
+const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+export async function validate() {
+    const checks = [];
+    const registry = lexiconRegistry();
+    const missing = REQUIRED_NAMES.filter((n) => !(n in registry));
+    checks.push(missing.length === 0
+        ? { name: "required-names", ok: true }
+        : { name: "required-names", ok: false, error: `Missing required names: ${missing.join(", ")}` });
+    const bad = digestMismatches();
+    checks.push(bad.length === 0
+        ? { name: "schemas-match-pin", ok: true }
+        : { name: "schemas-match-pin", ok: false, error: `Vendored schemas differ from GRAFANA_SCHEMA_PIN: ${bad.map((b) => b.name).join(", ")}` });
+    const stale = Object.entries(schemaModules())
+        .filter(([rel, source]) => {
+        try {
+            return readFileSync(join(pkgDir, rel), "utf-8") !== source;
+        }
+        catch {
+            return true;
+        }
+    })
+        .map(([rel]) => rel);
+    checks.push(stale.length === 0
+        ? { name: "schema-types-in-sync", ok: true }
+        : { name: "schema-types-in-sync", ok: false, error: `Run npm run generate: stale ${stale.join(", ")}` });
+    const classes = Object.entries(panels).filter((e) => typeof e[1] === "function" && "definition" in e[1]);
+    const broken = [];
+    for (const [name, Cls] of classes) {
+        try {
+            const json = renderDashboard(new Dashboard({ title: name, uid: "validate", panels: [new Cls({ title: name })] }));
+            const problems = validateDashboardSchema(json);
+            if (problems.length > 0)
+                broken.push(`${name} (${problems[0].path}: ${problems[0].message})`);
+        }
+        catch (err) {
+            broken.push(`${name} (${err instanceof Error ? err.message : String(err)})`);
+        }
+    }
+    checks.push(broken.length === 0
+        ? { name: "panels-match-schema", ok: true }
+        : { name: "panels-match-schema", ok: false, error: `Panels whose dashboard fails the schema: ${broken.join(", ")}` });
+    checks.push(BUILTIN_CATALOG.length === Object.keys(registry).length
+        ? { name: "catalog-matches-registry", ok: true }
+        : { name: "catalog-matches-registry", ok: false, error: "catalog and registry disagree" });
+    return { success: checks.every((c) => c.ok), checks };
+}

package/dist/validation.js

@@ -0,0 +1,13 @@
+/**
+ * `@intentius/chant-lexicon-grafana/validation`: the GRAF101-GRAF117 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, } from "./validate-output.js";
+export { validateDashboardSchema, validateExpressionSchema, schemaValidationUnavailable, } from "./schema-validate.js";

package/dist/variables.js

@@ -0,0 +1,70 @@
+/**
+ * Dashboard variables (Grafana's "templating"): query, custom, interval,
+ * 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
+ * expression; GRAF103 checks every such reference names a declared
+ * variable. A `DatasourceVariable` can stand in for a datasource on a panel
+ * or query, and the reference becomes `${name}`.
+ */
+import { createProperty } from "@intentius/chant/runtime";
+/** The kinds Grafana can repeat a panel or row over: the ones that hold a list of values (`MultiValueVariable` in @grafana/scenes). */
+export const MULTI_VALUE_KINDS = new Set(["query", "custom", "datasource", "groupby"]);
+export const VARIABLE_TYPE_PREFIX = "Grafana::Variable::";
+function variableClass(kind, className) {
+    const Base = createProperty(`${VARIABLE_TYPE_PREFIX}${kind}`, "grafana");
+    const Cls = function (props) {
+        Base.call(this, props);
+        Object.defineProperty(this, "variableKind", { value: kind, enumerable: false });
+        Object.defineProperty(this, "variableName", { value: props.name, enumerable: false });
+        if (kind === "datasource") {
+            Object.defineProperty(this, "pluginType", { value: props.pluginType, enumerable: false });
+        }
+    };
+    Object.defineProperty(Cls, "name", { value: className });
+    return Cls;
+}
+/** A variable whose values come from a datasource query. */
+export const QueryVariable = variableClass("query", "QueryVariable");
+/** A variable with a fixed list of values. */
+export const CustomVariable = variableClass("custom", "CustomVariable");
+/** A time interval to choose, used as `$name` in range selectors. */
+export const IntervalVariable = variableClass("interval", "IntervalVariable");
+/** A choice of datasource of one plugin type. Usable wherever a datasource is. */
+export const DatasourceVariable = variableClass("datasource", "DatasourceVariable");
+/** A hidden, fixed value. */
+export const ConstantVariable = variableClass("constant", "ConstantVariable");
+/** A free-text box. */
+export const TextboxVariable = variableClass("textbox", "TextboxVariable");
+/**
+ * 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 const AdhocVariable = variableClass("adhoc", "AdhocVariable");
+/**
+ * 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 const GroupByVariable = variableClass("groupby", "GroupByVariable");
+/** An on/off switch, `$name` being `enabledValue` or `disabledValue`. New in Grafana 12.3. */
+export const SwitchVariable = variableClass("switch", "SwitchVariable");
+export function isVariableEntity(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        value.lexicon === "grafana" &&
+        typeof value.entityType === "string" &&
+        value.entityType.startsWith(VARIABLE_TYPE_PREFIX));
+}
+export function isDatasourceVariable(value) {
+    return isVariableEntity(value) && value.variableKind === "datasource";
+}
+/** Variable names Grafana defines itself; queries may use them without declaring anything. */
+export function isBuiltinVariable(name) {
+    return name.startsWith("__") || name === "timeFilter" || name === "interval" || name === "interval_ms";
+}
+/** A valid variable name: what `$name` can match. */
+export const VARIABLE_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-grafana",
-  "version": "0.124.30",
+  "version": "0.124.32",
   "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",
@@ -36,22 +36,22 @@
     ".": {
       "development": "./src/index.ts",
       "types": "./dist/index.d.ts",
-      "default": "./src/index.ts"
+      "default": "./dist/index.js"
     },
     "./*": {
       "development": "./src/*.ts",
       "types": "./dist/*.d.ts",
-      "default": "./src/*.ts"
+      "default": "./dist/*.js"
     },
     "./op/activities": {
       "development": "./src/op/activities/index.ts",
       "types": "./dist/op/activities/index.d.ts",
-      "default": "./src/op/activities/index.ts"
+      "default": "./dist/op/activities/index.js"
     },
     "./lint/post-synth": {
       "development": "./src/lint/post-synth/index.ts",
       "types": "./dist/lint/post-synth/index.d.ts",
-      "default": "./src/lint/post-synth/index.ts"
+      "default": "./dist/lint/post-synth/index.js"
     },
     "./manifest": "./dist/manifest.json",
     "./meta": "./dist/meta.json",
@@ -63,14 +63,14 @@
     "validate": "tsx src/validate-cli.ts",
     "docs": "tsx src/codegen/docs-cli.ts",
     "prepack": "npm run generate && npm run bundle && npm run validate && npm run build",
-    "build": "../../scripts/tsc7.sh -p tsconfig.build.json && tsc-alias -p tsconfig.build.json && find dist -type f \\( -name \"*.js\" -o -name \"*.js.map\" \\) -delete"
+    "build": "../../scripts/tsc7.sh -p tsconfig.build.json --sourceMap false && tsc-alias -p tsconfig.build.json"
   },
   "dependencies": {
     "@grafana/lezer-logql": "0.4.2",
     "@grafana/lezer-traceql": "1.0.3",
-    "@intentius/chant-lexicon-k8s": "^0.124.30",
-    "@intentius/chant-lexicon-otel": "^0.124.30",
-    "@intentius/chant-lexicon-prometheus": "^0.124.30",
+    "@intentius/chant-lexicon-k8s": "^0.124.32",
+    "@intentius/chant-lexicon-otel": "^0.124.32",
+    "@intentius/chant-lexicon-prometheus": "^0.124.32",
     "@lezer/lr": "^1.4.10",
     "ajv": "^8.20.0",
     "js-yaml": "^4.3.1"
@@ -83,7 +83,7 @@
     "zod": "^4.3.6"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.124.30",
+    "@intentius/chant": "^0.124.32",
     "zod": "^4.3.6"
   }
 }

package/src/codegen/package.ts

@@ -4,7 +4,7 @@
 
 import { readFileSync } from "fs";
 import { join, dirname } from "path";
-import { fileURLToPath } from "url";
+import { moduleSourceDir } from "@intentius/chant/module-source";
 import {
   packagePipeline,
   collectSkills,
@@ -17,7 +17,7 @@ import { grafanaSkills } from "../skill-defs";
 export type { PackageOptions, PackageResult };
 
 // src/codegen/package.ts -> src/
-const srcDir = dirname(dirname(fileURLToPath(import.meta.url)));
+const srcDir = dirname(moduleSourceDir(import.meta.url));
 
 export async function packageLexicon(opts: PackageOptions = {}): Promise<PackageResult> {
   const pkgJson = JSON.parse(readFileSync(join(srcDir, "..", "package.json"), "utf-8"));

package/src/spec/fetch-notifiers-cli.ts

@@ -15,7 +15,7 @@
 import { execFileSync } from "child_process";
 import { writeFileSync } from "fs";
 import { dirname, join } from "path";
-import { fileURLToPath } from "url";
+import { moduleSourceDir } from "@intentius/chant/module-source";
 import { GRAFANA_NOTIFIERS_SOURCE, renderNotifiers, type NotifierResponse } from "./notifiers";
 
 /** curl, not fetch: the response is read from a Grafana the caller runs, and the egress catalogue lists only the commands that reach a remote host. */
@@ -50,6 +50,6 @@ async function viaDocker(): Promise<NotifierResponse[]> {
 }
 
 const notifiers = process.argv[2] ? readFrom(process.argv[2].replace(/\/$/, "")) : await viaDocker();
-const out = join(dirname(fileURLToPath(import.meta.url)), "..", "contact-point-settings.gen.ts");
+const out = join(moduleSourceDir(import.meta.url), "..", "contact-point-settings.gen.ts");
 writeFileSync(out, renderNotifiers(notifiers));
 console.log(`wrote ${out} (${notifiers.length} integrations)`);

package/src/spec/fetch-units-cli.ts

@@ -8,7 +8,7 @@
  */
 import { writeFileSync } from "fs";
 import { dirname, join } from "path";
-import { fileURLToPath } from "url";
+import { moduleSourceDir } from "@intentius/chant/module-source";
 import { sha256 } from "./schemas";
 import { GRAFANA_UNITS_SOURCE, LEGACY_UNIT_ALIASES } from "./units";
 
@@ -33,5 +33,5 @@ export const GRAFANA_UNIT_IDS: readonly string[] = [
 ${ids.map((id) => `  ${JSON.stringify(id)},`).join("\n")}
 ];
 `;
-writeFileSync(join(dirname(fileURLToPath(import.meta.url)), "units.gen.ts"), out);
+writeFileSync(join(moduleSourceDir(import.meta.url), "units.gen.ts"), out);
 console.error(`${ids.length} unit ids from ${repo}@${ref} written to src/spec/units.gen.ts`);

package/src/spec/overlay.ts

@@ -19,7 +19,7 @@
 
 import { existsSync, readFileSync } from "fs";
 import { dirname, join } from "path";
-import { fileURLToPath } from "url";
+import { moduleSourceDir } from "@intentius/chant/module-source";
 import type { SchemaName } from "../pin";
 
 export interface OverlayPatch {
@@ -42,7 +42,7 @@ export interface SchemaOverlay {
 }
 
 export function overlayDir(): string {
-  return join(dirname(fileURLToPath(import.meta.url)), "overlay");
+  return join(moduleSourceDir(import.meta.url), "overlay");
 }
 
 export function overlayPath(name: SchemaName): string {

package/src/spec/schemas.ts

@@ -13,13 +13,13 @@
 import { createHash } from "crypto";
 import { readFileSync } from "fs";
 import { dirname, join } from "path";
-import { fileURLToPath } from "url";
+import { moduleSourceDir } from "@intentius/chant/module-source";
 import { GRAFANA_SCHEMA_PIN, VENDORED_SCHEMA_NAMES, type SchemaName, type VendoredSchemaName } from "../pin";
 import { applyOverlay, loadOverlay } from "./overlay";
 
 /** Where the vendored files live: beside this module, under `src/`. */
 export function schemasDir(): string {
-  return join(dirname(fileURLToPath(import.meta.url)), "schemas");
+  return join(moduleSourceDir(import.meta.url), "schemas");
 }
 
 export function schemaPath(name: VendoredSchemaName): string {