@intentius/chant-lexicon-grafana 0.96.0

package/src/lint/post-synth/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/src/lint/post-synth/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/src/lint/post-synth/index.ts

@@ -0,0 +1,19 @@
+// Code generated by chant generate. DO NOT EDIT.
+import type { PostSynthCheck } from "@intentius/chant/lint/post-synth";
+import { graf101 } from "./graf101";
+import { graf102 } from "./graf102";
+import { graf103 } from "./graf103";
+import { graf104 } from "./graf104";
+import { graf105 } from "./graf105";
+import { graf106 } from "./graf106";
+import { graf107 } from "./graf107";
+
+export const postSynthChecks: PostSynthCheck[] = [
+  graf101,
+  graf102,
+  graf103,
+  graf104,
+  graf105,
+  graf106,
+  graf107,
+];

package/src/lint/post-synth/post-synth.test.ts

@@ -0,0 +1,231 @@
+import { describe, expect, test } from "vitest";
+import { makePostSynthCtxFromFiles, makePostSynthCtx } from "@intentius/chant-test-utils";
+import type { PostSynthCheck } from "@intentius/chant/lint/post-synth";
+import type { Declarable } from "@intentius/chant/declarable";
+import { grafanaSerializer } from "../../serializer";
+import { Datasource } from "../../datasource";
+import { Dashboard } from "../../dashboard";
+import { Row, StatPanel, TimeSeriesPanel, TablePanel } from "../../panels";
+import { PromQuery, TempoQuery } from "../../query";
+import { DatasourceVariable, QueryVariable } from "../../variables";
+import { graf101 } from "./graf101";
+import { graf102 } from "./graf102";
+import { graf103 } from "./graf103";
+import { graf104 } from "./graf104";
+import { graf105 } from "./graf105";
+import { graf106 } from "./graf106";
+import { graf107 } from "./graf107";
+
+/** Serialize entities the way a build does and hand the files to the harness. */
+function ctxOf(entities: Record<string, Declarable>) {
+  const out = grafanaSerializer.serialize(new Map(Object.entries(entities)));
+  if (typeof out === "string") throw new Error("expected files");
+  return makePostSynthCtxFromFiles("grafana", out.files!, out.primary, new Map(Object.entries(entities)));
+}
+
+/** A context from hand-written dashboard JSON and datasources, for shapes the typed API can't produce. */
+function ctxOfJson(dashboard: Record<string, unknown>, datasources: Array<Record<string, unknown>> = []) {
+  const files: Record<string, string> = { "dashboards/d.json": JSON.stringify(dashboard) };
+  if (datasources.length > 0) files["provisioning/datasources/chant.yaml"] = JSON.stringify({ apiVersion: 1, datasources });
+  return makePostSynthCtxFromFiles("grafana", files, "{}");
+}
+
+function ids(check: PostSynthCheck, ctx: ReturnType<typeof ctxOf>) {
+  return check.check(ctx).map((d) => [d.checkId, d.severity]);
+}
+
+const prometheus = new Datasource({ name: "Prometheus", type: "prometheus" });
+const tempo = new Datasource({ name: "Tempo", type: "tempo" });
+const up = new PromQuery({ expr: "sum(up)" });
+
+function panelJson(extra: Record<string, unknown>) {
+  return { type: "stat", id: 1, title: "p", gridPos: { x: 0, y: 0, w: 6, h: 4 }, options: {}, fieldConfig: { defaults: {}, overrides: [] }, ...extra };
+}
+
+function dashboardJson(panels: unknown[], variables: unknown[] = [], extra: Record<string, unknown> = {}) {
+  return { uid: "d", title: "D", schemaVersion: 42, annotations: { list: [] }, templating: { list: variables }, panels, ...extra };
+}
+
+describe("GRAF101: undeclared datasource", () => {
+  test("flags a ref to a uid nobody declares", () => {
+    const panel = new StatPanel({ datasource: { type: "prometheus", uid: "mimir" }, targets: [up] });
+    const diags = graf101.check(ctxOf({ prometheus, d: new Dashboard({ title: "D", panels: [panel] }) }));
+    expect(diags.map((d) => d.checkId)).toEqual(["GRAF101", "GRAF101"]);
+    expect(diags[0].message).toContain('"mimir"');
+    expect(diags[0].severity).toBe("error");
+  });
+
+  test("warns about queries with no datasource at all", () => {
+    const diags = graf101.check(ctxOf({ prometheus, d: new Dashboard({ title: "D", panels: [new StatPanel({ targets: [up] })] }) }));
+    expect(diags.map((d) => [d.checkId, d.severity])).toEqual([["GRAF101", "warning"]]);
+  });
+
+  test("flags a query variable on an undeclared datasource", () => {
+    const v = new QueryVariable({ name: "job", datasource: { type: "prometheus", uid: "gone" }, query: "label_values(job)" });
+    expect(ids(graf101, ctxOf({ prometheus, d: new Dashboard({ title: "D", variables: [v] }) }))).toEqual([["GRAF101", "error"]]);
+  });
+
+  test("passes declared datasources, datasource variables and Grafana's pseudo-datasources", () => {
+    const ds = new DatasourceVariable({ name: "ds", pluginType: "prometheus" });
+    const mixed = new TablePanel({ targets: [new PromQuery({ expr: "up", datasource: prometheus }), new TempoQuery({ query: "{}", datasource: tempo })] });
+    const d = new Dashboard({ title: "D", variables: [ds], panels: [new StatPanel({ datasource: prometheus, targets: [up] }), new StatPanel({ datasource: ds, targets: [up] }), mixed] });
+    expect(graf101.check(ctxOf({ prometheus, tempo, d }))).toEqual([]);
+  });
+
+  test("is silent when the build declares no datasource (another build root, chant #1939)", () => {
+    const panel = new StatPanel({ datasource: { type: "prometheus", uid: "elsewhere" }, targets: [up] });
+    expect(graf101.check(ctxOf({ d: new Dashboard({ title: "D", panels: [panel] }) }))).toEqual([]);
+  });
+});
+
+describe("GRAF102: datasource type mismatch", () => {
+  test("flags a query sent to a datasource of another type", () => {
+    const panel = new StatPanel({ datasource: { type: "prometheus", uid: "tempo" }, targets: [up] });
+    const diags = graf102.check(ctxOf({ tempo, d: new Dashboard({ title: "D", panels: [panel] }) }));
+    expect(diags.length).toBeGreaterThanOrEqual(1);
+    expect(diags[0].message).toContain("which is tempo");
+  });
+
+  test("flags a ref through a datasource variable of another plugin type", () => {
+    const dash = dashboardJson(
+      [panelJson({ datasource: { type: "prometheus", uid: "${ds}" }, targets: [{ refId: "A", expr: "up", datasource: { type: "prometheus", uid: "${ds}" } }] })],
+      [{ type: "datasource", name: "ds", query: "loki" }],
+    );
+    const diags = graf102.check(ctxOfJson(dash, [{ name: "Loki", type: "loki", uid: "loki" }]));
+    expect(diags[0].message).toContain('variable "ds" chooses among loki');
+  });
+
+  test("passes matching types", () => {
+    expect(graf102.check(ctxOf({ prometheus, d: new Dashboard({ title: "D", panels: [new StatPanel({ datasource: prometheus, targets: [up] })] }) }))).toEqual([]);
+  });
+});
+
+describe("GRAF103: undeclared variables", () => {
+  test("flags $name, ${name} and [[name]] the dashboard doesn't declare", () => {
+    const q = new PromQuery({ expr: 'rate(x{job="$job", env="${env:regex}"}[$__rate_interval])', legendFormat: "[[instance]]" });
+    const diags = graf103.check(ctxOf({ d: new Dashboard({ title: "D", panels: [new StatPanel({ title: "for $svc", datasource: prometheus, targets: [q] })] }) }));
+    expect(diags.map((d) => d.message.match(/uses \$(\w+)/)![1]).sort()).toEqual(["env", "instance", "job", "svc"]);
+  });
+
+  test("flags an undeclared repeat variable and variable query reference", () => {
+    const v = new QueryVariable({ name: "instance", datasource: prometheus, query: 'label_values(up{job="$job"}, instance)' });
+    const diags = graf103.check(ctxOf({ d: new Dashboard({ title: "D", variables: [v], panels: [new StatPanel({ repeat: "pod" })] }) }));
+    expect(diags.map((d) => d.message)).toEqual([expect.stringContaining("repeat uses $pod"), expect.stringContaining('variable "instance" query uses $job')]);
+  });
+
+  test("passes declared variables and Grafana's built-ins", () => {
+    const job = new QueryVariable({ name: "job", datasource: prometheus, query: "label_values(up, job)" });
+    const q = new PromQuery({ expr: 'rate(x{job="$job"}[$__rate_interval]) / $__range_s', legendFormat: "{{job}}" });
+    const d = new Dashboard({ title: "D", variables: [job], panels: [new StatPanel({ datasource: prometheus, targets: [q], repeat: job })] });
+    expect(graf103.check(ctxOf({ d }))).toEqual([]);
+  });
+});
+
+describe("GRAF104: duplicates", () => {
+  test("flags duplicate dashboard uids, datasource names and panel ids", () => {
+    const again = new Datasource({ name: "Prometheus", type: "prometheus", uid: "prom-2" });
+    const d1 = new Dashboard({ title: "A", uid: "same", panels: [new StatPanel({ id: 7 }), new StatPanel({ id: 7 })] });
+    const d2 = new Dashboard({ title: "B", uid: "same" });
+    const messages = graf104.check(ctxOf({ prometheus, again, d1, d2 })).map((d) => d.message);
+    expect(messages).toEqual([
+      expect.stringContaining('share the uid "same"'),
+      expect.stringContaining('share the name "Prometheus"'),
+      expect.stringContaining("2 panels with id 7"),
+    ]);
+  });
+
+  test("flags duplicate refIds and variable names", () => {
+    const dash = dashboardJson(
+      [panelJson({ targets: [{ refId: "A", expr: "a" }, { refId: "A", expr: "b" }] })],
+      [{ type: "textbox", name: "q" }, { type: "textbox", name: "q" }],
+    );
+    expect(graf104.check(ctxOfJson(dash)).map((d) => d.message)).toEqual([
+      expect.stringContaining('variable "q" 2 times'),
+      expect.stringContaining('refId "A"'),
+    ]);
+  });
+
+  test("passes unique ids", () => {
+    expect(graf104.check(ctxOf({ prometheus, tempo, a: new Dashboard({ title: "A", panels: [new StatPanel(), new StatPanel()] }), b: new Dashboard({ title: "B" }) }))).toEqual([]);
+  });
+});
+
+describe("GRAF105: grid", () => {
+  test("flags a panel past column 24 as an error and an overlap as a warning", () => {
+    const d = new Dashboard({
+      title: "D",
+      panels: [
+        new StatPanel({ title: "wide", gridPos: { x: 20, y: 0, w: 8, h: 4 } }),
+        new TimeSeriesPanel({ title: "a", gridPos: { x: 0, y: 10, w: 12, h: 8 } }),
+        new TimeSeriesPanel({ title: "b", gridPos: { x: 6, y: 12, w: 12, h: 8 } }),
+      ],
+    });
+    expect(ids(graf105, ctxOf({ d }))).toEqual([
+      ["GRAF105", "error"],
+      ["GRAF105", "warning"],
+    ]);
+  });
+
+  test("compares a collapsed row's panels with each other only", () => {
+    const d = new Dashboard({
+      title: "D",
+      panels: [new StatPanel({ title: "top" }), new Row({ title: "r", collapsed: true, panels: [new StatPanel({ gridPos: { x: 0, y: 0, w: 6, h: 4 } })] })],
+    });
+    expect(graf105.check(ctxOf({ d }))).toEqual([]);
+  });
+
+  test("passes a dashboard laid out by chant", () => {
+    const panels = [new StatPanel(), new TimeSeriesPanel(), new Row({ title: "r", panels: [new TablePanel(), new TablePanel(), new TablePanel()] })];
+    expect(graf105.check(ctxOf({ d: new Dashboard({ title: "D", panels }) }))).toEqual([]);
+  });
+});
+
+describe("GRAF106: uids and titles", () => {
+  test("flags an over-long uid, a bad datasource uid and an empty title", () => {
+    const bad = new Datasource({ name: "Bad", type: "prometheus", uid: "has space" });
+    const d = new Dashboard({ title: "", uid: "x".repeat(41) });
+    expect(graf106.check(ctxOf({ bad, d })).map((x) => x.message)).toEqual([
+      expect.stringContaining("has uid"),
+      expect.stringContaining("has no title"),
+      expect.stringContaining('Datasource "Bad"'),
+    ]);
+  });
+
+  test("passes valid uids", () => {
+    expect(graf106.check(ctxOf({ prometheus, d: new Dashboard({ title: "Fine", uid: "svc_overview-1" }) }))).toEqual([]);
+  });
+});
+
+describe("GRAF107: the pinned schema", () => {
+  test("flags an unknown dashboard key, a bad panel option and an unknown query field", () => {
+    const dash = dashboardJson(
+      [panelJson({ options: { graphMode: "sparkline" }, datasource: { type: "prometheus", uid: "p" }, targets: [{ refId: "A", expr: "up", exprr: "typo" }] })],
+      [],
+      { owner: "team-a" },
+    );
+    const messages = graf107.check(ctxOfJson(dash)).map((d) => d.message);
+    expect(messages).toEqual([
+      expect.stringContaining('must NOT have additional properties ("owner")'),
+      expect.stringContaining("/panels/0/options/graphMode: must be equal to one of the allowed values"),
+      expect.stringContaining('/panels/0/targets/0: must NOT have additional properties ("exprr")'),
+    ]);
+  });
+
+  test("flags a row and a panel missing what the schema requires", () => {
+    const dash = dashboardJson([{ type: "row", title: "r" }, { title: "no type" }]);
+    const messages = graf107.check(ctxOfJson(dash)).map((d) => d.message);
+    expect(messages.some((m) => m.includes("/panels/0: must have required property 'collapsed'"))).toBe(true);
+    expect(messages.some((m) => m.includes("/panels/1: must have required property 'type'"))).toBe(true);
+  });
+
+  test("passes everything the typed API emits", () => {
+    const d = new Dashboard({ title: "D", panels: [new StatPanel({ datasource: prometheus, targets: [up], options: { graphMode: "none" } })] });
+    expect(graf107.check(ctxOf({ prometheus, d }))).toEqual([]);
+  });
+
+  test("checks a dashboard in another lexicon's output too", () => {
+    const dash = dashboardJson([panelJson({ options: { colorMode: "rainbow" } })]);
+    const ctx = makePostSynthCtx("k8s", JSON.stringify(dash));
+    expect(graf107.check(ctx).map((d) => d.checkId)).toEqual(["GRAF107"]);
+  });
+});

package/src/lint/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/src/lint/rules/index.ts

@@ -0,0 +1,9 @@
+import type { LintRule } from "@intentius/chant/lint/rule";
+import { uidSyntaxRule } from "./uid-syntax";
+import { literalSecretRule } from "./literal-secret";
+
+export { uidSyntaxRule } from "./uid-syntax";
+export { literalSecretRule } from "./literal-secret";
+
+/** All lint rules provided by this lexicon (imported by plugin.ts's lintRules()). */
+export const rules: LintRule[] = [uidSyntaxRule, literalSecretRule];

package/src/lint/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/src/lint/rules/rules.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, test } from "vitest";
+import * as ts from "typescript";
+import type { LintContext } from "@intentius/chant/lint/rule";
+import { uidSyntaxRule } from "./uid-syntax";
+import { literalSecretRule } from "./literal-secret";
+
+function ctx(code: string): LintContext {
+  const sourceFile = ts.createSourceFile("dashboard.ts", code, ts.ScriptTarget.Latest, true);
+  return { sourceFile, entities: [], filePath: "dashboard.ts" };
+}
+
+describe("GRAF001 uid and variable-name syntax", () => {
+  test("flags an over-long or ill-formed uid and an unusable variable name", () => {
+    const diags = uidSyntaxRule.check(
+      ctx(`
+        new Dashboard({ title: "x", uid: "${"a".repeat(41)}" });
+        new Datasource({ name: "P", type: "prometheus", uid: "has space" });
+        new QueryVariable({ name: "my-var", datasource: p, query: "q" });
+        new CustomVariable({ name: "1st", values: [] });
+      `),
+    );
+    expect(diags.map((d) => [d.ruleId, d.line])).toEqual([
+      ["GRAF001", 2],
+      ["GRAF001", 3],
+      ["GRAF001", 4],
+      ["GRAF001", 5],
+    ]);
+  });
+
+  test("follows a props object declared as a const", () => {
+    const diags = uidSyntaxRule.check(ctx(`const props = { title: "x", uid: "bad/uid" };\nnew Dashboard(props);`));
+    expect(diags).toHaveLength(1);
+  });
+
+  test("accepts valid values, non-literals and other constructors", () => {
+    const diags = uidSyntaxRule.check(
+      ctx(`
+        new Dashboard({ title: "x", uid: "svc-overview_1" });
+        new Dashboard({ title: "x", uid: someUid });
+        new TextboxVariable({ name: "trace_id" });
+        new Deployment({ uid: "not grafana at all" });
+      `),
+    );
+    expect(diags).toEqual([]);
+  });
+});
+
+describe("GRAF002 literal secret", () => {
+  test("flags a literal in secureJsonData, inline or through a const", () => {
+    const diags = literalSecretRule.check(
+      ctx(`
+        new Datasource({ name: "P", type: "prometheus", secureJsonData: { basicAuthPassword: "hunter2" } });
+        const secrets = { httpHeaderValue1: "Bearer abc" };
+        new Datasource({ name: "T", type: "tempo", secureJsonData: secrets });
+      `),
+    );
+    expect(diags.map((d) => d.ruleId)).toEqual(["GRAF002", "GRAF002"]);
+    expect(diags[0].message).toContain("basicAuthPassword");
+  });
+
+  test("accepts values Grafana expands and other constructors", () => {
+    const diags = literalSecretRule.check(
+      ctx(`
+        new Datasource({ name: "P", type: "prometheus", secureJsonData: { a: "$__env{PROM_PASSWORD}", b: "$__file{/run/secrets/token}", c: "\${TOKEN}", d: "$TOKEN" } });
+        new Secret({ secureJsonData: { password: "not ours" } });
+      `),
+    );
+    expect(diags).toEqual([]);
+  });
+});

package/src/lint/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;
+  },
+};

package/src/lsp/completions.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from "vitest";
+import { completions } from "./completions";
+
+describe("grafana LSP completions", () => {
+  it("offers the panel classes after new", () => {
+    const content = 'import { TimeSeriesPanel } from "@intentius/chant-lexicon-grafana";\nconst p = new Time';
+    const items = completions({
+      uri: "file:///dashboard.ts",
+      content,
+      position: { line: 1, character: content.split("\n")[1].length },
+      wordAtCursor: "Time",
+      linePrefix: "const p = new Time",
+    });
+    expect(items.map((i) => i.label)).toContain("TimeSeriesPanel");
+  });
+
+  it("offers the query classes by prefix", () => {
+    const items = completions({
+      uri: "file:///q.ts",
+      content: "new Prom",
+      position: { line: 0, character: 8 },
+      wordAtCursor: "Prom",
+      linePrefix: "new Prom",
+    });
+    expect(items.map((i) => i.label)).toContain("PromQuery");
+  });
+
+  it("returns an array for an empty context", () => {
+    expect(Array.isArray(completions({} as never))).toBe(true);
+  });
+});

package/src/lsp/completions.ts

@@ -0,0 +1,15 @@
+import type { CompletionContext, CompletionItem } from "@intentius/chant/lsp/types";
+import { LexiconIndex, lexiconCompletions } from "@intentius/chant/lsp/lexicon-providers";
+import { lexiconRegistry } from "../catalog";
+
+let cachedIndex: LexiconIndex | null = null;
+
+function getIndex(): LexiconIndex {
+  cachedIndex ??= new LexiconIndex(lexiconRegistry());
+  return cachedIndex;
+}
+
+/** Completions for the grafana entity classes: dashboards, datasources, panels, queries and variables. */
+export function completions(ctx: CompletionContext): CompletionItem[] {
+  return lexiconCompletions(ctx, getIndex(), "Grafana entity");
+}