@intentius/chant-lexicon-grafana 0.96.0

package/dist/query.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Typed queries, one class per datasource plugin: `PromQuery` (PromQL),
+ * `TempoQuery` (TraceQL) and `LokiQuery` (LogQL), each typed from that
+ * plugin's query schema at `GRAFANA_SCHEMA_PIN`.
+ *
+ * The expression is a string; this lexicon does not parse PromQL, TraceQL or
+ * LogQL. What it does check is where the query goes: `datasource` only
+ * accepts a datasource of the query's own plugin type, and GRAF101, GRAF102
+ * and GRAF103 check the emitted references after a build.
+ *
+ * `defineQuery` is the extension point for any other datasource plugin, and
+ * the three built-ins are defined through it.
+ */
+import type { Declarable } from "@intentius/chant/declarable";
+import type { DatasourceEntity, DatasourceRef } from "./datasource.js";
+import type { DatasourceVariableEntity } from "./variables.js";
+import type { SchemaName } from "./pin.js";
+import type { Dataquery as PrometheusDataquery } from "./schema/prometheus.gen.js";
+import type { Dataquery as TempoDataquery } from "./schema/tempo.gen.js";
+import type { Dataquery as LokiDataquery } from "./schema/loki.gen.js";
+/** Where a query or panel sends its request: a declared datasource, a datasource variable, or the ref of one declared elsewhere. */
+export type DatasourceInput<T extends string = string> = DatasourceEntity<T> | DatasourceVariableEntity<T> | DatasourceRef<T>;
+/** A query model's fields, less what chant fills in (`datasource`, `refId` stays optional). */
+export type QueryModel<M> = Omit<M, "datasource">;
+export type QueryProps<M, T extends string> = QueryModel<M> & {
+    /** Overrides the panel's datasource for this query. */
+    datasource?: DatasourceInput<T>;
+};
+export interface QueryDefinition<T extends string = string, M = Record<string, unknown>> {
+    /** The datasource plugin id this query is for. */
+    datasourceType: T;
+    /** The class name, for hover and docs. */
+    className: string;
+    description?: string;
+    /** The vendored schema the model follows, when there is one (GRAF107 validates against it). */
+    schema?: SchemaName;
+    /** Which field holds the expression, for GRAF103 and hover. */
+    expressionField?: string;
+    /** Fields the schema requires that Grafana fills in anyway, written when the author leaves them out. */
+    defaults?: Partial<M>;
+    /** True only for the queries this package ships. */
+    builtin: boolean;
+}
+export interface QueryEntity<T extends string = string, M = Record<string, unknown>> extends Declarable {
+    readonly props: QueryProps<M, T>;
+    readonly queryDefinition: QueryDefinition<T, M>;
+}
+export interface QueryClass<T extends string = string, M = Record<string, unknown>> {
+    new (props: QueryProps<M, T>): QueryEntity<T, M>;
+    readonly definition: QueryDefinition<T, M>;
+}
+export declare const QUERY_TYPE_PREFIX = "Grafana::Query::";
+/** Every registered query definition, keyed by datasource type. */
+export declare function registeredQueries(): QueryDefinition[];
+export declare function queryDefinitionFor(datasourceType: string): QueryDefinition | undefined;
+/**
+ * Define a query class for a datasource plugin chant doesn't ship.
+ *
+ * @example
+ * ```ts
+ * interface ElasticQueryModel { query: string; metrics?: Array<{ type: string; id: string }>; refId?: string }
+ *
+ * export const ElasticQuery = defineQuery<ElasticQueryModel>()({
+ *   datasourceType: "elasticsearch",
+ *   className: "ElasticQuery",
+ *   expressionField: "query",
+ * });
+ * ```
+ */
+export declare function defineQuery<M>(): <T extends string>(def: Omit<QueryDefinition<T, M>, "builtin">) => QueryClass<T, M>;
+export declare function isQueryEntity(value: unknown): value is QueryEntity;
+/** A Prometheus query: `expr` is PromQL. */
+export declare const PromQuery: QueryClass<"prometheus", PrometheusDataquery>;
+/** A Tempo query: `query` is TraceQL. `filters` defaults to none. */
+export declare const TempoQuery: QueryClass<"tempo", Omit<TempoDataquery, "filters"> & Partial<Pick<TempoDataquery, "filters">>>;
+/** A Loki query: `expr` is LogQL. */
+export declare const LokiQuery: QueryClass<"loki", LokiDataquery>;
+export type PromQueryEntity = InstanceType<typeof PromQuery>;
+export type TempoQueryEntity = InstanceType<typeof TempoQuery>;
+export type LokiQueryEntity = InstanceType<typeof LokiQuery>;
+//# sourceMappingURL=query.d.ts.map

package/dist/query.d.ts.map

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

package/dist/rules/graf101.ts

@@ -0,0 +1,17 @@
+/**
+ * GRAF101: A panel, query or variable uses a datasource no Datasource in the build declares
+ *
+ * Grafana shows "datasource not found" on the panel. Typed references cannot go wrong this way, so it mostly catches a { type, uid } ref or a hand-edited dashboard. A panel with queries and no datasource at all is a warning: Grafana sends them to its default datasource. This check joins dashboards against the Datasource declarations of the same build root, so it goes silent across build roots (chant #1939): with no Datasource declared in the build it reports nothing, and a datasource declared in another build root looks undeclared. Keep datasources and the dashboards that use them in one build root.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { grafanaDiagnostics } from "./grafana-helpers";
+
+export const graf101: PostSynthCheck = {
+  id: "GRAF101",
+  description: "A panel, query or variable uses a datasource no Datasource in the build declares",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return grafanaDiagnostics(ctx, "GRAF101");
+  },
+};

package/dist/rules/graf102.ts

@@ -0,0 +1,17 @@
+/**
+ * GRAF102: A query is sent to a datasource of another plugin type
+ *
+ * A PromQL query sent to Tempo fails at query time. The typed classes prevent this at compile time; the check catches refs, datasource variables of the wrong plugin type and hand-edited dashboards. Like GRAF101 it joins against the Datasource declarations of the same build root and goes silent across build roots (chant #1939).
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { grafanaDiagnostics } from "./grafana-helpers";
+
+export const graf102: PostSynthCheck = {
+  id: "GRAF102",
+  description: "A query is sent to a datasource of another plugin type",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return grafanaDiagnostics(ctx, "GRAF102");
+  },
+};

package/dist/rules/graf103.ts

@@ -0,0 +1,17 @@
+/**
+ * GRAF103: A query, title, datasource or repeat uses a variable the dashboard does not declare
+ *
+ * Grafana leaves an undeclared $name in the query as text, so the query fails or matches nothing. Names Grafana defines itself ($__interval, $__rate_interval, $__range and the rest of $__*) need no declaration.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { grafanaDiagnostics } from "./grafana-helpers";
+
+export const graf103: PostSynthCheck = {
+  id: "GRAF103",
+  description: "A query, title, datasource or repeat uses a variable the dashboard does not declare",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return grafanaDiagnostics(ctx, "GRAF103");
+  },
+};

package/dist/rules/graf104.ts

@@ -0,0 +1,17 @@
+/**
+ * GRAF104: Two dashboards, datasources, panels, variables or queries share an id
+ *
+ * Dashboard uids and datasource uids and names must be unique across the build, panel ids and variable names within a dashboard, and refIds within a panel. Grafana keeps one of two dashboards with the same uid and silently drops the other.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { grafanaDiagnostics } from "./grafana-helpers";
+
+export const graf104: PostSynthCheck = {
+  id: "GRAF104",
+  description: "Two dashboards, datasources, panels, variables or queries share an id",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return grafanaDiagnostics(ctx, "GRAF104");
+  },
+};

package/dist/rules/graf105.ts

@@ -0,0 +1,17 @@
+/**
+ * GRAF105: A panel does not fit the 24-column grid, or overlaps another panel
+ *
+ * A panel wider than the grid is an error. An overlap is a warning: Grafana moves one of the panels on load, so the dashboard does not look the way it was declared. Panels without x and y are placed by the dashboard and cannot overlap each other.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { grafanaDiagnostics } from "./grafana-helpers";
+
+export const graf105: PostSynthCheck = {
+  id: "GRAF105",
+  description: "A panel does not fit the 24-column grid, or overlaps another panel",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return grafanaDiagnostics(ctx, "GRAF105");
+  },
+};

package/dist/rules/graf106.ts

@@ -0,0 +1,17 @@
+/**
+ * GRAF106: A dashboard or datasource uid Grafana rejects, or a dashboard with no title
+ *
+ * Grafana accepts uids of 1-40 letters, digits, - and _, and refuses to save a dashboard without a title.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { grafanaDiagnostics } from "./grafana-helpers";
+
+export const graf106: PostSynthCheck = {
+  id: "GRAF106",
+  description: "A dashboard or datasource uid Grafana rejects, or a dashboard with no title",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return grafanaDiagnostics(ctx, "GRAF106");
+  },
+};

package/dist/rules/graf107.ts

@@ -0,0 +1,17 @@
+/**
+ * GRAF107: A dashboard does not match the pinned Grafana schema
+ *
+ * The dashboard is validated against the dashboard schema at GRAFANA_SCHEMA_PIN, and each panel's options, fieldConfig.defaults.custom and queries against their plugin's schema with required fields relaxed (Grafana fills those in). What fails is a key the schema does not have or a value it does not allow: the edits Grafana would otherwise need on import.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { grafanaDiagnostics } from "./grafana-helpers";
+
+export const graf107: PostSynthCheck = {
+  id: "GRAF107",
+  description: "A dashboard does not match the pinned Grafana schema",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return grafanaDiagnostics(ctx, "GRAF107");
+  },
+};

package/dist/rules/grafana-ast.ts

@@ -0,0 +1,70 @@
+import * as ts from "typescript";
+
+/** The constructor name of a `new X(...)` or `X(...)` expression, if it is a plain or dotted name. */
+export function calleeName(node: ts.CallExpression | ts.NewExpression): string | undefined {
+  const callee = node.expression;
+  if (ts.isIdentifier(callee)) return callee.text;
+  if (ts.isPropertyAccessExpression(callee)) return callee.name.text;
+  return undefined;
+}
+
+/** A property's key as text, for identifier and string-literal keys. */
+export function propertyName(prop: ts.ObjectLiteralElementLike): string | undefined {
+  if (!ts.isPropertyAssignment(prop)) return undefined;
+  if (ts.isIdentifier(prop.name) || ts.isStringLiteral(prop.name)) return prop.name.text;
+  return undefined;
+}
+
+/** The text of a string literal or substitution-free template, else undefined. */
+export function literalText(node: ts.Expression): string | undefined {
+  if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) return node.text;
+  return undefined;
+}
+
+export function position(source: ts.SourceFile, node: ts.Node): { line: number; column: number } {
+  const { line, character } = source.getLineAndCharacterOfPosition(node.getStart(source));
+  return { line: line + 1, column: character + 1 };
+}
+
+/** `const name = <init>` declarations in the file, so a value written as a named const can be followed. */
+export function constInitializers(source: ts.SourceFile): Map<string, ts.Expression> {
+  const out = new Map<string, ts.Expression>();
+  const visit = (node: ts.Node) => {
+    if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer) out.set(node.name.text, node.initializer);
+    ts.forEachChild(node, visit);
+  };
+  visit(source);
+  return out;
+}
+
+/** Follow an identifier to the object literal it was declared as, when it is one in this file. */
+export function resolveObject(node: ts.Expression, consts: Map<string, ts.Expression>, depth = 0): ts.ObjectLiteralExpression | undefined {
+  let n: ts.Expression = node;
+  while (ts.isAsExpression(n) || ts.isSatisfiesExpression(n) || ts.isParenthesizedExpression(n)) n = n.expression;
+  if (ts.isObjectLiteralExpression(n)) return n;
+  if (ts.isIdentifier(n) && depth < 5) {
+    const init = consts.get(n.text);
+    if (init) return resolveObject(init, consts, depth + 1);
+  }
+  return undefined;
+}
+
+/** The first object-literal argument of every `new <Name>(...)` or `<Name>(...)` for the names given. */
+export function constructorArgs(
+  source: ts.SourceFile,
+  names: (name: string) => boolean,
+): Array<{ name: string; arg: ts.ObjectLiteralExpression }> {
+  const consts = constInitializers(source);
+  const out: Array<{ name: string; arg: ts.ObjectLiteralExpression }> = [];
+  const visit = (node: ts.Node) => {
+    if (ts.isNewExpression(node) || ts.isCallExpression(node)) {
+      const name = calleeName(node);
+      const first = node.arguments?.[0];
+      const arg = first ? resolveObject(first, consts) : undefined;
+      if (name && arg && names(name)) out.push({ name, arg });
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(source);
+  return out;
+}

package/dist/rules/grafana-helpers.ts

@@ -0,0 +1,68 @@
+/**
+ * Shared plumbing for the grafana post-synth checks: find the dashboards and
+ * provisioned datasources in a build's output, and run the plain-function
+ * checks in `validate-output.ts` over them.
+ *
+ * Any output file shaped like a dashboard or a datasource provisioning file
+ * counts, not only the grafana lexicon's own, so a dashboard another lexicon
+ * embeds is checked the same way.
+ */
+
+import type { PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import type { SerializerResult } from "@intentius/chant/serializer";
+import { loadAll } from "js-yaml";
+import { looksLikeDashboard, looksLikeDatasourceProvisioning } from "../../detect";
+import type { ProvisionedDatasource } from "../../build";
+import { issuesFor, type GrafanaArtifacts, type GrafanaIssueCode } from "../../validate-output";
+
+function parse(text: string, name: string): unknown[] {
+  if (name.endsWith(".json") || /^\s*[{[]/.test(text)) {
+    try {
+      return [JSON.parse(text)];
+    } catch {
+      // fall through to YAML
+    }
+  }
+  try {
+    return loadAll(text);
+  } catch {
+    return [];
+  }
+}
+
+/** Every dashboard and provisioned datasource in the build's output. */
+export function grafanaArtifacts(ctx: PostSynthContext): GrafanaArtifacts {
+  const out: GrafanaArtifacts = { dashboards: [], datasources: [] };
+  for (const [lexicon, output] of ctx.outputs) {
+    const texts: Array<[string, string]> =
+      typeof output === "string"
+        ? [[lexicon, output]]
+        : [[lexicon, (output as SerializerResult).primary], ...Object.entries((output as SerializerResult).files ?? {})];
+    for (const [source, text] of texts) {
+      if (!text) continue;
+      for (const doc of parse(text, source)) {
+        if (looksLikeDashboard(doc)) out.dashboards.push({ source, json: doc });
+        else if (looksLikeDatasourceProvisioning(doc)) {
+          for (const d of doc.datasources) {
+            if (d && typeof d === "object" && typeof (d as ProvisionedDatasource).name === "string") {
+              const ds = d as ProvisionedDatasource;
+              out.datasources.push({ ...ds, uid: typeof ds.uid === "string" ? ds.uid : ds.name });
+            }
+          }
+        }
+      }
+    }
+  }
+  return out;
+}
+
+/** Diagnostics for one check across the build's output. */
+export function grafanaDiagnostics(ctx: PostSynthContext, code: GrafanaIssueCode): PostSynthDiagnostic[] {
+  return issuesFor(code, grafanaArtifacts(ctx)).map((i) => ({
+    checkId: i.code,
+    severity: i.severity,
+    message: i.message,
+    ...(i.entity ? { entity: i.entity } : {}),
+    lexicon: "grafana",
+  }));
+}

package/dist/rules/literal-secret.ts

@@ -0,0 +1,48 @@
+import * as ts from "typescript";
+import type { LintRule, LintDiagnostic, LintContext } from "@intentius/chant/lint/rule";
+import { constInitializers, constructorArgs, literalText, position, propertyName, resolveObject } from "./grafana-ast";
+
+/** How Grafana provisioning reads a value from outside the file: `$VAR`, `${VAR}`, `$__env{…}`, `$__file{…}`, `$__vault{…}`. */
+const EXPANDED = /\$(\{[A-Za-z_][A-Za-z0-9_]*\}|[A-Za-z_][A-Za-z0-9_]*|__(env|file|vault)\{[^}]+\})/;
+
+/**
+ * GRAF002: a datasource secret written as a literal.
+ *
+ * `secureJsonData` holds passwords, tokens and TLS keys. A literal there is a
+ * secret in the repository and in the emitted provisioning file. Grafana
+ * expands `$__env{NAME}`, `$__file{/path}` and `${NAME}` when it reads the
+ * file, so the declaration never needs the value. A value written as a
+ * named `const` in the same file is followed.
+ */
+export const literalSecretRule: LintRule = {
+  id: "GRAF002",
+  severity: "error",
+  category: "security",
+  description: "Datasource secureJsonData value declared as a literal instead of $__env{...} or $__file{...}",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const diagnostics: LintDiagnostic[] = [];
+    const source = context.sourceFile;
+    const consts = constInitializers(source);
+    for (const { arg } of constructorArgs(source, (n) => n === "Datasource")) {
+      for (const prop of arg.properties) {
+        if (propertyName(prop) !== "secureJsonData") continue;
+        const secure = resolveObject((prop as ts.PropertyAssignment).initializer, consts);
+        if (!secure) continue;
+        for (const entry of secure.properties) {
+          if (!ts.isPropertyAssignment(entry)) continue;
+          const text = literalText(entry.initializer);
+          if (text === undefined || text === "" || EXPANDED.test(text)) continue;
+          diagnostics.push({
+            ruleId: "GRAF002",
+            severity: "error",
+            message: `secureJsonData.${propertyName(entry) ?? "?"} is a literal secret; write "$__env{NAME}" or "$__file{/path}" and let Grafana read it`,
+            file: context.filePath,
+            ...position(source, entry.initializer),
+          });
+        }
+      }
+    }
+    return diagnostics;
+  },
+};

package/dist/rules/uid-syntax.ts

@@ -0,0 +1,56 @@
+import type * as ts from "typescript";
+import type { LintRule, LintDiagnostic, LintContext } from "@intentius/chant/lint/rule";
+import { UID_PATTERN } from "../../util";
+import { VARIABLE_NAME } from "../../variables";
+import { constructorArgs, literalText, position, propertyName } from "./grafana-ast";
+
+const UID_OWNERS = new Set(["Dashboard", "Datasource"]);
+const VARIABLE_CLASS = /Variable$/;
+
+/**
+ * GRAF001: a uid Grafana rejects, or a variable name queries cannot reference.
+ *
+ * A literal `uid` on a `Dashboard` or `Datasource` must be 1-40 letters,
+ * digits, `-` and `_`; Grafana refuses anything else on import. A literal
+ * `name` on a `*Variable` must be letters, digits and `_`, starting with a
+ * letter or `_`, or `$name` in a query cannot refer to it. Caught in source,
+ * before a build; GRAF106 checks the emitted uids too.
+ */
+export const uidSyntaxRule: LintRule = {
+  id: "GRAF001",
+  severity: "error",
+  category: "correctness",
+  description: "Dashboard or datasource uid Grafana rejects, or a variable name queries can't reference",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const diagnostics: LintDiagnostic[] = [];
+    const source = context.sourceFile;
+    for (const { name, arg } of constructorArgs(source, (n) => UID_OWNERS.has(n) || VARIABLE_CLASS.test(n))) {
+      for (const prop of arg.properties) {
+        const key = propertyName(prop);
+        if (!key) continue;
+        const text = literalText((prop as ts.PropertyAssignment).initializer);
+        if (text === undefined) continue;
+        if (UID_OWNERS.has(name) && key === "uid" && !UID_PATTERN.test(text)) {
+          diagnostics.push({
+            ruleId: "GRAF001",
+            severity: "error",
+            message: `${name} uid "${text}" is not a Grafana uid; use 1-40 letters, digits, "-" and "_"`,
+            file: context.filePath,
+            ...position(source, prop),
+          });
+        }
+        if (VARIABLE_CLASS.test(name) && key === "name" && !VARIABLE_NAME.test(text)) {
+          diagnostics.push({
+            ruleId: "GRAF001",
+            severity: "error",
+            message: `variable name "${text}" can't be referenced as $name; use letters, digits and "_", not starting with a digit`,
+            file: context.filePath,
+            ...position(source, prop),
+          });
+        }
+      }
+    }
+    return diagnostics;
+  },
+};