@intentius/chant-lexicon-grafana 0.97.0 → 0.99.0

package/src/import/embedded.ts

@@ -0,0 +1,47 @@
+/**
+ * Dashboard JSON embedded in another lexicon's resource, for `chant import`
+ * (#2962): a k8s ConfigMap holding a dashboard, as the Grafana dashboard
+ * sidecar (the `grafana_dashboard` label) and file provisioning both mount
+ * them. Matching is by content, so a dashboard in an unlabelled ConfigMap
+ * is imported too.
+ *
+ * The dashboard is imported exactly as `chant import dashboard.json` would
+ * import it, into a directory of its own, and the host's value becomes
+ * `dashboardJson(dashboard)`, the JSON text the grafana serializer writes.
+ */
+
+import type { EmbeddedContentImporter, EmbeddedImport } from "@intentius/chant/import/embedded";
+import { looksLikeDashboard, looksLikeV2Dashboard } from "../detect";
+import { DASHBOARD_RESOURCE_TYPE, parseGrafana, type PlanResourceProperties } from "./parser";
+import { generatePlanModules } from "./generator";
+
+const PACKAGE = "@intentius/chant-lexicon-grafana";
+
+export const dashboardImporter: EmbeddedContentImporter = {
+  what: "a Grafana dashboard",
+
+  matches(content) {
+    if (typeof content.text !== "string" || content.select !== undefined) return false;
+    return looksLikeDashboard(content.document) && !looksLikeV2Dashboard(content.document);
+  },
+
+  import(content): EmbeddedImport {
+    const ir = parseGrafana(content.text!);
+    const resource = ir.resources.find((r) => r.type === DASHBOARD_RESOURCE_TYPE);
+    if (!resource) throw new Error((ir.warnings ?? []).join(" ") || "no dashboard was read");
+    const { plan } = resource.properties as unknown as PlanResourceProperties;
+    // Core gives the content a directory of its own; the plan's would nest a second one inside it.
+    const { files, exported } = generatePlanModules({ ...plan, directory: "" });
+    const dashboard = exported.get("dashboard");
+    if (!dashboard) throw new Error("the import declared no dashboard");
+    return {
+      files,
+      value: {
+        bindings: [{ from: dashboard.path, name: dashboard.name }],
+        shape: "single",
+        through: { from: PACKAGE, name: "dashboardJson" },
+      },
+      warnings: ir.warnings ?? [],
+    };
+  },
+};

package/src/import/generated-types.e2e.test.ts

@@ -0,0 +1,118 @@
+/**
+ * The generated source type-checks against the lexicon's types. Compiling
+ * the corpus takes longer than the unit-test budget allows, so this runs
+ * with the e2e tests.
+ *
+ * Grafana's UI exports, the alerting provisioning corpus and what the
+ * examples build type-check clean. A
+ * community dashboard can carry keys the pinned schemas do not list (query
+ * fields from older Grafana versions such as `step` and `metric`, panel
+ * options added after the pin): it still imports and builds back to the
+ * same JSON, GRAF107 warns about each key, and tsc points at the const or
+ * constructor that holds it. Those are pinned here, per fixture, so a
+ * change to the generator or the types that adds or removes one is seen.
+ */
+import { describe, expect, test } from "vitest";
+import { mkdirSync, mkdtempSync } from "fs";
+import { join } from "path";
+import * as ts from "typescript";
+import { GrafanaParser } from "./parser";
+import { GrafanaGenerator } from "./generator";
+import { ALERTING, COMMUNITY, KUBE_PROMETHEUS, UI_EXPORTS, V2_EXPORTS, exampleOutputs, pkgDir, read, removeDir, repoRoot, writeFiles } from "./testdata/fixtures";
+
+type Files = Array<{ path: string; content: string }>;
+
+/** Type errors in generated projects, compiled together against the lexicon's source with the repo's compiler options. */
+function typeErrors(projects: Record<string, Files>): string[] {
+  const dir = mkdtempSync(join(pkgDir, ".roundtrip-tmp-"));
+  try {
+    const files: string[] = [];
+    for (const [name, generated] of Object.entries(projects)) {
+      const sub = join(dir, name.replace(/[^A-Za-z0-9]+/g, "-"));
+      mkdirSync(sub);
+      files.push(...writeFiles(sub, generated));
+    }
+    const configFile = ts.readConfigFile(join(repoRoot, "tsconfig.json"), ts.sys.readFile);
+    const parsed = ts.parseJsonConfigFileContent(configFile.config, ts.sys, repoRoot);
+    const program = ts.createProgram(files, { ...parsed.options, noEmit: true });
+    const real = (f: string) => ts.sys.realpath?.(f) ?? f;
+    const fileSet = new Set(files.map(real));
+    const diagnostics = ts.getPreEmitDiagnostics(program).filter((d) => d.file && fileSet.has(real(d.file.fileName)));
+    // A program that saw none of the files would pass vacuously.
+    expect(files.every((f) => program.getSourceFile(f) !== undefined)).toBe(true);
+    return diagnostics.map((d) => {
+      const at = real(d.file!.fileName).slice(real(dir).length + 1);
+      return `${at}: ${ts.flattenDiagnosticMessageText(d.messageText, " ")}`;
+    });
+  } finally {
+    removeDir(dir);
+  }
+}
+
+const generate = (content: string): Files => new GrafanaGenerator().generate(new GrafanaParser().parse(content));
+
+/**
+ * Error counts by the property tsc names, for a compact pin of what a
+ * fixture carries outside the types. tsc names only the first unknown key
+ * of an object literal, so a count is a lower bound (GRAF107 lists them all).
+ */
+function byProperty(errors: string[]): Record<string, number> {
+  const out: Record<string, number> = {};
+  for (const e of errors) {
+    const m = /'([^']+)' does not exist in type/.exec(e);
+    const key = m ? m[1] : e.replace(/^[^:]+: /, "");
+    out[key] = (out[key] ?? 0) + 1;
+  }
+  return out;
+}
+
+describe("the generated source type-checks against the lexicon's types", () => {
+  test("Grafana's UI exports, the v2 dashboards and the examples' dashboards type-check clean", async () => {
+    const projects: Record<string, Files> = Object.fromEntries([...UI_EXPORTS, ...V2_EXPORTS].map((f) => [f, generate(read(f))]));
+    for (const [name, text] of await exampleOutputs()) {
+      if (/^[^/]+\/dashboards\/.*\.json$/.test(name)) projects[name] = generate(text);
+    }
+    expect(typeErrors(projects)).toEqual([]);
+  }, 180_000);
+
+  test("alerting provisioning files, and what the alerting example builds, type-check clean", async () => {
+    const projects: Record<string, Files> = Object.fromEntries(ALERTING.map((f) => [f, generate(read(f))]));
+    for (const [name, text] of await exampleOutputs()) {
+      if (name.endsWith("provisioning/alerting/chant.yaml")) projects[name] = generate(text);
+    }
+    expect(Object.keys(projects).some((n) => n.startsWith("alerting/"))).toBe(true);
+    expect(typeErrors(projects)).toEqual([]);
+  }, 180_000);
+
+  test("community dashboards: what they carry outside the pinned types is where tsc points", () => {
+    const found: Record<string, Record<string, number>> = {};
+    for (const file of COMMUNITY) found[file] = byProperty(typeErrors({ [file]: generate(read(file)) }));
+    expect(found).toEqual({
+      "community/node-exporter-full.json": { step: 273, metric: 1 },
+      "community/k8s-views-global.json": {},
+      "community/k8s-views-pods.json": { footer: 3 },
+      "community/traefik.json": {},
+      "community/redis.json": { metric: 11, step: 6, time_options: 1, unitScale: 13 },
+      "community/prometheus-2-stats.json": { metric: 3, now: 1, step: 18 },
+      "community/prometheus-2-stats.grafana-12.4.11.json": { metric: 3, step: 18 },
+    });
+  }, 300_000);
+
+  test("kube-prometheus's dashboards: what they carry outside the pinned types is where tsc points", () => {
+    const projects: Record<string, Files> = Object.fromEntries(KUBE_PROMETHEUS.map((f) => [f, generate(read(f))]));
+    // Compiled as one program: a project's files are under its fixture path, made a directory name.
+    const errors = typeErrors(projects);
+    const found = Object.fromEntries(
+      KUBE_PROMETHEUS.map((f) => [f, byProperty(errors.filter((e) => e.startsWith(`${f.replace(/[^A-Za-z0-9]+/g, "-")}/`)))] as const).filter(([, v]) => Object.keys(v).length > 0),
+    );
+    expect(Object.values(found).reduce((n, v) => n + Object.values(v).reduce((a, b) => a + b, 0), 0)).toBe(errors.length);
+    // Values GRAF107 reports in the source dashboards (roundtrip.test.ts), plus keys the pinned schemas do not list. The node
+    // dashboards' merge transformation without options type-checks: the typed transformation classes do not require it.
+    expect(found).toEqual({
+      "kube-prometheus/grafana-overview.json": { "Type 'string' is not assignable to type 'string[]'.": 1, alertThreshold: 2 },
+      "kube-prometheus/k8s-resources-pod.json": { "Type '\"thresholds\"' is not assignable to type 'AxisColorMode | undefined'.": 1 },
+      "kube-prometheus/namespace-by-pod.json": { index: 6 },
+      "kube-prometheus/pod-total.json": { index: 6 },
+    });
+  }, 300_000);
+});

package/src/import/generator.test.ts

@@ -0,0 +1,210 @@
+import { describe, expect, test } from "vitest";
+import { GrafanaGenerator, generatePlan, DECLARABLES_PER_FILE } from "./generator";
+import { callValue, declRef, type Declaration, type Plan } from "./model";
+
+function plan(declarations: Declaration[], extra: Partial<Plan> = {}): Plan {
+  const keys = [...new Set(declarations.map((d) => d.module))];
+  return {
+    directory: "",
+    modules: keys.map((key) => ({ key, file: key, summary: `The ${key}` })),
+    declarations,
+    customClasses: [],
+    exports: ["dashboard"],
+    ...extra,
+  };
+}
+
+const panel = (n: number, props: Record<string, unknown> = {}, module = "panels"): Declaration => ({
+  id: `panel:${n}`,
+  kind: "new",
+  className: "StatPanel",
+  props: { title: `Panel ${n}`, ...props },
+  name: `Panel ${n}`,
+  module,
+  unit: `panel:${n}`,
+});
+
+const query = (n: number, refId: string, module = "panels"): Declaration => ({
+  id: `query:${n}:${refId}`,
+  kind: "new",
+  className: "PromQuery",
+  props: { expr: "up", refId },
+  name: { of: `panel:${n}`, suffix: refId },
+  module,
+  unit: `panel:${n}`,
+});
+
+const dash = (panels: string[]): Declaration => ({
+  id: "dashboard",
+  kind: "new",
+  className: "Dashboard",
+  props: { title: "D", panels: panels.map(declRef) },
+  name: "D",
+  module: "dashboard",
+});
+
+const file = (files: Array<{ path: string; content: string }>, path: string) => {
+  const f = files.find((x) => x.path === path);
+  if (!f) throw new Error(`no ${path} in ${files.map((x) => x.path).join(", ")}`);
+  return f.content;
+};
+
+describe("names", () => {
+  test("from titles, with a query named after its panel and refId", () => {
+    const files = generatePlan(plan([query(1, "A"), panel(1, { targets: [declRef("query:1:A")] }), dash(["panel:1"])]));
+    const panels = file(files, "panels.ts");
+    expect(panels).toContain('const panel1A = new PromQuery({ expr: "up", refId: "A" });');
+    expect(panels).toContain('const panel1 = new StatPanel({ title: "Panel 1", targets: [panel1A] });');
+  });
+
+  test("an all-caps name is one word; reserved words, clashes and leading digits are avoided", () => {
+    const decls: Declaration[] = [
+      { id: "variable:DS_PROMETHEUS", kind: "new", className: "DatasourceVariable", props: { name: "DS_PROMETHEUS", pluginType: "prometheus" }, name: "DS_PROMETHEUS", module: "variables" },
+      { id: "variable:default", kind: "new", className: "TextboxVariable", props: { name: "default" }, name: "default", module: "variables" },
+      { id: "variable:x", kind: "new", className: "TextboxVariable", props: { name: "x" }, name: "404 errors", module: "variables" },
+      { id: "variable:y", kind: "new", className: "TextboxVariable", props: { name: "y" }, name: "default", module: "variables" },
+      dash([]),
+    ];
+    const body = file(generatePlan(plan(decls)), "variables.ts");
+    expect(body).toContain("const dsPrometheus = new DatasourceVariable(");
+    expect(body).toContain("const default2 = new TextboxVariable(");
+    expect(body).toContain("const variable404Errors = new TextboxVariable(");
+    expect(body).toContain("const default3 = new TextboxVariable(");
+  });
+});
+
+describe("literals", () => {
+  test("a nested value is lifted into a const typed by the class's props (COR001)", () => {
+    const files = generatePlan(plan([panel(1, { gridPos: { x: 0, y: 0, w: 6, h: 4 }, options: { reduceOptions: { calcs: ["last"] } } }), dash(["panel:1"])]));
+    const panels = file(files, "panels.ts");
+    expect(panels).toContain('import { type PropsOf, StatPanel } from "@intentius/chant-lexicon-grafana";');
+    expect(panels).toContain('const panel1GridPos: PropsOf<typeof StatPanel>["gridPos"] = { x: 0, y: 0, w: 6, h: 4 };');
+    expect(panels).toContain('const panel1Options: PropsOf<typeof StatPanel>["options"] = { reduceOptions: { calcs: ["last"] } };');
+    expect(panels).toContain("gridPos: panel1GridPos,");
+  });
+
+  test("lists of strings and of references stay inline", () => {
+    const files = generatePlan(plan([{ ...dash([]), props: { title: "D", tags: ["a", "b"] } }]));
+    expect(file(files, "dashboard.ts")).toContain('const d = new Dashboard({ title: "D", tags: ["a", "b"] });');
+  });
+
+  test("a value declaration carries its type annotation and imports the type", () => {
+    const files = generatePlan(
+      plan([
+        { id: "ds", kind: "value", value: { type: "prometheus", uid: "prom" }, type: { text: 'DatasourceRef<"prometheus">', imports: ["DatasourceRef"] }, name: "prom", module: "datasources" },
+        panel(1, { datasource: declRef("ds") }),
+        dash(["panel:1"]),
+      ]),
+    );
+    expect(file(files, "datasources.ts")).toContain('import { type DatasourceRef } from "@intentius/chant-lexicon-grafana";');
+    expect(file(files, "datasources.ts")).toContain('const prom: DatasourceRef<"prometheus"> = { type: "prometheus", uid: "prom" };');
+    expect(file(files, "panels.ts")).toContain('import { prom } from "./datasources";');
+    expect(file(files, "datasources.ts")).toMatch(/export \{ prom \};\n$/);
+  });
+
+  test("multi-line strings become template literals with ${ escaped; quotes pick the lighter form", () => {
+    const files = generatePlan(plan([panel(1, { description: "line one\nuses ${var} and `ticks`", title: 'say "hi"' }), dash(["panel:1"])]));
+    const body = file(files, "panels.ts");
+    expect(body).toContain("description: `line one\nuses \\${var} and \\`ticks\\``");
+    expect(body).toContain(`title: 'say "hi"'`);
+  });
+});
+
+describe("modules", () => {
+  test(`a group over ${DECLARABLES_PER_FILE} declarables is split, a panel kept with its queries (COR009)`, () => {
+    const decls: Declaration[] = [];
+    for (let n = 0; n < 7; n++) decls.push(query(n, "A"), query(n, "B"), panel(n, { targets: [declRef(`query:${n}:A`), declRef(`query:${n}:B`)] }));
+    decls.push(dash(Array.from({ length: 7 }, (_, n) => `panel:${n}`)));
+    const files = generatePlan(plan(decls));
+    const panelFiles = files.filter((f) => f.path.startsWith("panels-"));
+    expect(panelFiles.map((f) => f.path)).toEqual(["panels-1.ts", "panels-2.ts", "panels-3.ts", "panels-4.ts"]);
+    for (const f of panelFiles) {
+      expect((f.content.match(/ = new /g) ?? []).length).toBeLessThanOrEqual(DECLARABLES_PER_FILE);
+      // Every panel sits with its two queries.
+      const panels = [...f.content.matchAll(/const (panel\d+) = new StatPanel/g)].map((m) => m[1]);
+      for (const p of panels) expect(f.content).toContain(`const ${p}A = new PromQuery(`);
+    }
+    expect(panelFiles[0].content).toContain("/** The panels (1 of 4) */");
+    expect(file(files, "dashboard.ts")).toContain('import { panel0, panel1 } from "./panels-1";');
+  });
+
+  test("a panel with more queries than fit in one file is split across files", () => {
+    const decls: Declaration[] = [];
+    const refs = "ABCDEFGHIJ".split("");
+    for (const r of refs) decls.push(query(0, r));
+    decls.push(panel(0, { targets: refs.map((r) => declRef(`query:0:${r}`)) }), dash(["panel:0"]));
+    const files = generatePlan(plan(decls)).filter((f) => f.path.startsWith("panels-"));
+    expect(files.map((f) => (f.content.match(/ = new /g) ?? []).length)).toEqual([8, 3]);
+    expect(files[1].content).toContain('from "./panels-1";');
+  });
+
+  test("only what another module imports is exported, besides the plan's exports", () => {
+    const files = generatePlan(plan([query(1, "A"), panel(1, { targets: [declRef("query:1:A")] }), dash(["panel:1"])]));
+    expect(file(files, "panels.ts")).toMatch(/export \{ panel1 \};\n$/);
+    expect(file(files, "dashboard.ts")).toMatch(/export \{ d \};\n$/);
+  });
+
+  test("a directory holds the plan's modules, and imports stay relative to it", () => {
+    const files = generatePlan(plan([panel(1), dash(["panel:1"])], { directory: "my-board" }));
+    expect(files.map((f) => f.path)).toEqual(["my-board/panels.ts", "my-board/dashboard.ts"]);
+    expect(file(files, "my-board/dashboard.ts")).toContain('import { panel1 } from "./panels";');
+  });
+
+  test("a class the plan declares is written in plugins.ts and imported where it is used", () => {
+    const files = generatePlan(
+      plan([{ ...panel(1), className: "PiechartPanel", customClass: "panel-class:piechart" }, dash(["panel:1"])], {
+        customClasses: [
+          {
+            id: "panel-class:piechart",
+            className: "PiechartPanel",
+            factory: "definePanel",
+            definition: { type: "piechart", className: "PiechartPanel", defaultSize: { w: 12, h: 8 } },
+            comment: ["// not shipped"],
+          },
+        ],
+      }),
+    );
+    expect(file(files, "plugins.ts")).toBe(
+      [
+        "/** Classes for plugins chant has no class for */",
+        'import { definePanel } from "@intentius/chant-lexicon-grafana";',
+        "",
+        "// not shipped",
+        "const PiechartPanel = definePanel()({",
+        '  type: "piechart",',
+        '  className: "PiechartPanel",',
+        "  defaultSize: { w: 12, h: 8 },",
+        "});",
+        "",
+        "export { PiechartPanel };",
+        "",
+      ].join("\n"),
+    );
+    expect(file(files, "panels.ts")).toContain('import { PiechartPanel } from "./plugins";');
+    expect(file(files, "panels.ts")).not.toContain("@intentius/chant-lexicon-grafana");
+  });
+
+  test("a reference to something the plan does not declare is an error", () => {
+    expect(() => generatePlan(plan([dash(["panel:9"])]))).toThrow(/refers to "panel:9"/);
+  });
+});
+
+test("an IR with no dashboard (a v2 one, reported by the parser) generates nothing", () => {
+  expect(new GrafanaGenerator().generate({ resources: [], parameters: [] })).toEqual([]);
+});
+
+test("the generator owns its layout, so core writes its files as they are (#2964)", () => {
+  expect(new GrafanaGenerator().ownsLayout).toBe(true);
+});
+
+describe("call values (#2954)", () => {
+  test("a call is written with the package function imported, its last argument laid out like any value", () => {
+    const long = { excludeByName: Object.fromEntries(Array.from({ length: 8 }, (_, i) => [`field number ${i}`, true])) };
+    const transformations = [{ id: "merge", options: {} }, callValue("customTransformation", ["sortBy", { fields: {} }]), callValue("customTransformation", ["organize", long])];
+    const files = generatePlan(plan([panel(1, { transformations }), dash(["panel:1"])]));
+    const text = files.map((f) => f.content).join("\n");
+    expect(text).toMatch(/import \{[^}]*customTransformation[^}]*\} from "@intentius\/chant-lexicon-grafana";/);
+    expect(text).toContain('  customTransformation("sortBy", { fields: {} }),');
+    expect(text).toContain('  customTransformation("organize", {\n    excludeByName: {\n      "field number 0": true,');
+  });
+});