@intentius/chant-lexicon-prometheus 0.97.0 → 0.99.0

package/src/import/cli.test.ts

@@ -0,0 +1,98 @@
+/**
+ * `chant import <file>` end to end through core's import command: detection
+ * from a project that lists the prometheus lexicon, `--lexicon prometheus`
+ * without one, the files written, and `chant build` on them giving the file
+ * back.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "fs";
+import { join } from "path";
+import { load } from "js-yaml";
+import { build } from "@intentius/chant/build";
+import { importCommand } from "@intentius/chant/cli/commands/import";
+import { prometheusSerializer } from "../serializer";
+import { builtFiles, exampleOutputs, pkgDir, read } from "./testdata/fixtures";
+
+let dir: string;
+
+beforeEach(() => {
+  dir = mkdtempSync(join(pkgDir, ".roundtrip-tmp-"));
+});
+
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true });
+});
+
+function write(name: string, content: string): string {
+  const path = join(dir, name);
+  writeFileSync(path, content);
+  return path;
+}
+
+async function rebuilt(srcDir: string): Promise<{ rules?: string; alertmanager?: string }> {
+  const result = await build(srcDir, [prometheusSerializer]);
+  expect(result.errors).toEqual([]);
+  return builtFiles(result.outputs.get("prometheus"));
+}
+
+describe("chant import", () => {
+  test("detects a rule file in a project that lists prometheus", async () => {
+    writeFileSync(join(dir, "chant.config.json"), JSON.stringify({ lexicons: ["prometheus"] }));
+    const templatePath = write("rules.yml", read("rules-full.yml"));
+    const output = join(dir, "src");
+
+    const result = await importCommand({ templatePath, output });
+
+    expect(result.error).toBeUndefined();
+    expect(result.success).toBe(true);
+    expect(result.lexicon).toBe("prometheus");
+    expect(result.generatedFiles).toEqual(["rules.ts"]);
+    expect(readFileSync(join(output, "rules.ts"), "utf-8")).toContain("new RuleGroup(");
+    const { rules } = await rebuilt(output);
+    expect(load(rules!)).toEqual(expect.objectContaining({ groups: expect.any(Array) }));
+  }, 30_000);
+
+  test("detects an alertmanager.yml in a project that lists prometheus", async () => {
+    writeFileSync(join(dir, "chant.config.json"), JSON.stringify({ lexicons: ["prometheus"] }));
+    const am = (await exampleOutputs()).find((o) => o.name === "alerting/alertmanager.yml")!;
+    const templatePath = write("alertmanager.yml", am.yaml);
+    const output = join(dir, "src");
+
+    const result = await importCommand({ templatePath, output });
+
+    expect(result.error).toBeUndefined();
+    expect(result.lexicon).toBe("prometheus");
+    expect(result.generatedFiles).toEqual(["receivers.ts", "time-intervals.ts", "routes.ts", "inhibit-rules.ts", "settings.ts"]);
+    expect((await rebuilt(output)).alertmanager).toBe(am.yaml);
+  }, 30_000);
+
+  test("--lexicon prometheus imports without a project, and prints what it rewrote", async () => {
+    const templatePath = write("alertmanager.yml", read("alertmanager-full.yml"));
+    const output = join(dir, "src");
+
+    // Without a project, detection tries every installed lexicon (#2965).
+    const detected = await importCommand({ templatePath, output: join(dir, "detected") });
+    expect(detected.error).toBeUndefined();
+    expect(detected.lexicon).toBe("prometheus");
+    expect(detected.detected).toBe(true);
+
+    const result = await importCommand({ templatePath, output, lexicon: "prometheus" });
+
+    expect(result.error).toBeUndefined();
+    expect(result.success).toBe(true);
+    expect(result.lexicon).toBe("prometheus");
+    expect(result.warnings.some((w) => w.includes("match/match_re are written as matchers"))).toBe(true);
+    const { alertmanager } = await rebuilt(output);
+    expect(alertmanager).toContain('- severity="page"');
+    expect(alertmanager).toContain("name: weekends");
+  }, 30_000);
+
+  test("--lexicon prometheus on a file that is neither names both shapes", async () => {
+    const templatePath = write("collector.yaml", "receivers:\n  otlp: {}\nservice:\n  pipelines: {}\n");
+    const result = await importCommand({ templatePath, output: join(dir, "src"), lexicon: "prometheus" });
+    expect(result.success).toBe(false);
+    expect(result.error).toContain("rule file");
+    expect(result.error).toContain("alertmanager.yml");
+  });
+});

package/src/import/embedded.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, test } from "vitest";
+import { embeddedDocument, type EmbeddedContent } from "@intentius/chant/import/embedded";
+import { prometheusPlugin } from "../plugin";
+import { ruleGroupsImporter } from "./embedded";
+
+const GROUPS = [
+  { name: "api", rules: [{ alert: "ApiDown", expr: "up{job=\"api\"} == 0", for: "5m" }] },
+  { name: "recording", rules: [{ record: "job:up:sum", expr: "sum by (job) (up)" }] },
+];
+
+const RULE_FILE = `groups:
+  - name: api
+    rules:
+      - alert: ApiDown
+        expr: up{job="api"} == 0
+        for: 5m
+`;
+
+const site = (over: Partial<EmbeddedContent>): EmbeddedContent => ({
+  host: "k8s",
+  hostType: "K8s::Monitoring::PrometheusRule",
+  location: "PrometheusRule api spec.groups",
+  directory: "api",
+  ...over,
+});
+
+describe("rule groups embedded in another lexicon's resource (#2962)", () => {
+  test("the plugin registers the importer", () => {
+    expect(prometheusPlugin.embeddedImporters?.()).toEqual([ruleGroupsImporter]);
+  });
+
+  test("matches a PrometheusRule's groups and a rule file held as text; not an alertmanager.yml", () => {
+    expect(ruleGroupsImporter.matches(site({ document: { groups: GROUPS }, select: "groups" }))).toBe(true);
+    expect(ruleGroupsImporter.matches(site({ text: RULE_FILE, document: embeddedDocument(RULE_FILE) }))).toBe(true);
+    const am = "route:\n  receiver: x\nreceivers:\n  - name: x\n";
+    expect(ruleGroupsImporter.matches(site({ text: am, document: embeddedDocument(am) }))).toBe(false);
+  });
+
+  test("spec.groups becomes the list of declared groups, in the source's order", () => {
+    const out = ruleGroupsImporter.import(site({ document: { groups: GROUPS }, select: "groups" }));
+    expect(out.files.map((f) => f.path)).toEqual(["rules.ts"]);
+    expect(out.value).toEqual({
+      bindings: [
+        { from: "rules.ts", name: "api" },
+        { from: "rules.ts", name: "recording" },
+      ],
+      shape: "list",
+    });
+  });
+
+  test("a rule file held as text goes through ruleFileYaml", () => {
+    const out = ruleGroupsImporter.import(site({ text: RULE_FILE, document: embeddedDocument(RULE_FILE) }));
+    expect(out.value.through).toEqual({ from: "@intentius/chant-lexicon-prometheus", name: "ruleFileYaml" });
+    expect(out.value.bindings).toEqual([{ from: "rules.ts", name: "api" }]);
+  });
+});

package/src/import/embedded.ts

@@ -0,0 +1,44 @@
+/**
+ * Rule groups embedded in another lexicon's resource, for `chant import`
+ * (#2962): a k8s `PrometheusRule`'s `spec.groups`, or a rule file held as
+ * text in a ConfigMap.
+ *
+ * The groups are imported exactly as `chant import rules.yml` would import
+ * them, into a directory of its own. `spec.groups` becomes the list of the
+ * declared groups (an `Slo`'s by its `rules` member), which the k8s
+ * serializer renders as the same groups; a rule file becomes
+ * `ruleFileYaml([...])`, the text the prometheus serializer writes.
+ */
+
+import type { EmbeddedContentImporter, EmbeddedImport } from "@intentius/chant/import/embedded";
+import { looksLikeRuleFile } from "../model";
+import { parsePrometheusYaml } from "./parser";
+import { generateRuleFile } from "./generator";
+
+const PACKAGE = "@intentius/chant-lexicon-prometheus";
+
+export const ruleGroupsImporter: EmbeddedContentImporter = {
+  what: "Prometheus rule groups",
+
+  matches(content) {
+    if (!looksLikeRuleFile(content.document)) return false;
+    return content.select === "groups" || (content.select === undefined && typeof content.text === "string");
+  },
+
+  import(content): EmbeddedImport {
+    // JSON is YAML: the document goes through the same parser a rule file does.
+    const source = content.select === undefined ? content.text! : JSON.stringify(content.document);
+    const parsed = parsePrometheusYaml(source);
+    if (parsed.kind !== "rules") throw new Error("this is not a Prometheus rule file");
+    const { files, groups } = generateRuleFile(parsed.file);
+    const bindings = groups.map((g) => ({ from: g.path, name: g.name, ...(g.member ? { member: g.member } : {}) }));
+    return {
+      files,
+      value:
+        content.select === undefined
+          ? { bindings, shape: "list", through: { from: PACKAGE, name: "ruleFileYaml" } }
+          : { bindings, shape: "list" },
+      warnings: parsed.warnings,
+    };
+  },
+};

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

@@ -0,0 +1,77 @@
+/**
+ * The generated source type-checks against the lexicon's types. Compiling
+ * the generated projects takes longer than the unit-test budget allows, so
+ * this runs with the e2e tests.
+ */
+import { describe, expect, test } from "vitest";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "fs";
+import { join } from "path";
+import * as ts from "typescript";
+import { PrometheusParser } from "./parser";
+import { PrometheusGenerator } from "./generator";
+import { exampleOutputs, pkgDir, read, repoRoot, sloOutputs, UPSTREAM } 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);
+      for (const f of generated) {
+        writeFileSync(join(sub, f.path), f.content);
+        files.push(join(sub, f.path));
+      }
+    }
+    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, "\n")}`;
+    });
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+const generate = (yaml: string): Files => new PrometheusGenerator().generate(new PrometheusParser().parse(yaml));
+
+describe("the generated source type-checks against the lexicon's types", () => {
+  test("for every fixture", async () => {
+    const projects: Record<string, Files> = {
+      rulesFull: generate(read("rules-full.yml")),
+      alertmanagerFull: generate(read("alertmanager-full.yml")),
+      alertmanagerIntegrations: generate(read("alertmanager-integrations.yml")),
+      ...Object.fromEntries(UPSTREAM.map((f) => [f, generate(read("upstream", f))])),
+      ...Object.fromEntries(sloOutputs().map((o) => [o.name, generate(o.yaml)])),
+      ...Object.fromEntries((await exampleOutputs()).map((o) => [o.name, generate(o.yaml)])),
+    };
+    expect(typeErrors(projects)).toEqual([]);
+  }, 120_000);
+
+  test("a field outside a notifier's typed config is carried as found, and tsc points at it", () => {
+    const yaml = [
+      "route:",
+      "  receiver: chat",
+      "receivers:",
+      "  - name: chat",
+      "    slack_configs:",
+      "      - channel: '#alerts'",
+      "        api_url_file: /etc/alertmanager/slack-url",
+      "        message_text: '{{ .CommonLabels.alertname }}'",
+      "        mesage_txt: typo",
+      "",
+    ].join("\n");
+    const errors = typeErrors({ slack: generate(yaml) });
+    expect(errors).toEqual([expect.stringMatching(/^slack\/receivers\.ts: .*'mesage_txt' does not exist in type 'SlackConfig'/)]);
+  }, 120_000);
+});

package/src/import/generator.test.ts

@@ -0,0 +1,138 @@
+import { describe, expect, test } from "vitest";
+import type { AlertmanagerConfig, RuleGroupConfig } from "../model";
+import { generateAlertmanagerFiles, generateRuleFileFiles, PrometheusGenerator, tsLiteral } from "./generator";
+
+const byPath = (files: Array<{ path: string; content: string }>) => Object.fromEntries(files.map((f) => [f.path, f.content]));
+
+describe("rule files", () => {
+  test("a group is a Rule[] const of plain objects and a RuleGroup, exported by list", () => {
+    const files = byPath(
+      generateRuleFileFiles({
+        groups: [{ name: "api-slo", interval: "30s", labels: { team: "api" }, rules: [{ record: "a:b", expr: "sum(x)" }] }],
+      }),
+    );
+    expect(files["rules.ts"]).toBe(
+      [
+        "/** Rule groups */",
+        'import { type LabelSet, type Rule, RuleGroup } from "@intentius/chant-lexicon-prometheus";',
+        "",
+        'const apiSloLabels: LabelSet = { team: "api" };',
+        'const apiSloRules: Rule[] = [{ record: "a:b", expr: "sum(x)" }];',
+        "const apiSlo = new RuleGroup({",
+        '  name: "api-slo",',
+        '  interval: "30s",',
+        "  labels: apiSloLabels,",
+        "  rules: apiSloRules,",
+        "});",
+        "",
+        "export { apiSlo };",
+        "",
+      ].join("\n"),
+    );
+  });
+
+  test("more than eight groups are split across files, the limit COR009 sets", () => {
+    const groups: RuleGroupConfig[] = Array.from({ length: 10 }, (_, i) => ({ name: `g${i}`, rules: [] }));
+    const files = generateRuleFileFiles({ groups });
+    expect(files.map((f) => f.path)).toEqual(["rules-1.ts", "rules-2.ts"]);
+    expect(files[0].content).toContain("export { g0, g1, g2, g3, g4, g5, g6, g7 };");
+    expect(files[1].content).toContain("export { g8, g9 };");
+  });
+
+  test("names that clash or are not identifiers get a suffix", () => {
+    const files = byPath(
+      generateRuleFileFiles({
+        groups: [
+          { name: "default", rules: [] },
+          { name: "2xx", rules: [] },
+          { name: "Slo", rules: [] },
+          { name: "a.b", rules: [] },
+          { name: "a-b", rules: [] },
+        ],
+      }),
+    );
+    expect(files["rules.ts"]).toContain("export { defaultGroup, group2xx, slo, aB, aBGroup };");
+  });
+});
+
+describe("alertmanager.yml", () => {
+  const config: AlertmanagerConfig = {
+    route: {
+      receiver: "fallback",
+      routes: [
+        { receiver: "pager", matchers: ['severity="page"'], mute_time_intervals: ["nights", "undeclared"] },
+        { receiver: "elsewhere" },
+      ],
+    },
+    receivers: [
+      { name: "fallback" },
+      { name: "pager", pagerduty_configs: [{ routing_key_file: "/k" }] },
+    ],
+    time_intervals: [{ name: "nights", time_intervals: [{ times: [{ start_time: "00:00", end_time: "06:00" }] }] }],
+  };
+
+  test("routes reference receivers and time intervals by variable; names nothing declares stay strings", () => {
+    const files = byPath(generateAlertmanagerFiles(config));
+    expect(Object.keys(files)).toEqual(["receivers.ts", "time-intervals.ts", "routes.ts"]);
+    expect(files["routes.ts"]).toContain('import { fallback, pager } from "./receivers";');
+    expect(files["routes.ts"]).toContain('import { nights } from "./time-intervals";');
+    expect(files["routes.ts"]).toContain('mute_time_intervals: [nights, "undeclared"]');
+    expect(files["routes.ts"]).toContain('{ receiver: "elsewhere" }');
+    expect(files["routes.ts"]).toContain("const root = new Route({ receiver: fallback, routes: rootChildren });");
+  });
+
+  test("every integration Alertmanager defines is declared with its type", () => {
+    const files = byPath(
+      generateAlertmanagerFiles({
+        receivers: [{ name: "ops", opsgenie_configs: [{ api_key_file: "/k", priority: "P1" }], msteamsv2_configs: [{ webhook_url_file: "/t" }] }],
+      }),
+    );
+    expect(files["receivers.ts"]).toContain('const opsOpsgenie: OpsGenieConfig[] = [{ api_key_file: "/k", priority: "P1" }];');
+    expect(files["receivers.ts"]).toContain('const opsMsteamsv2: MSTeamsV2Config[] = [{ webhook_url_file: "/t" }];');
+    expect(files["receivers.ts"]).not.toContain("Untyped");
+  });
+
+  test("a receiver or global key Alertmanager doesn't define is spread in from an untyped const, with a comment", () => {
+    const files = byPath(
+      generateAlertmanagerFiles({
+        global: { resolve_timeout: "5m", pigeon_loft: "roof" } as never,
+        receivers: [{ name: "ops", pigeon_configs: [{ loft: "roof" }] } as never],
+      }),
+    );
+    expect(files["receivers.ts"]).toContain(
+      [
+        '// Receiver "ops": pigeon_configs is not a field Alertmanager v0.34.1 defines, so it is carried as',
+        "// data, untyped.",
+        'const opsUntyped = { pigeon_configs: [{ loft: "roof" }] };',
+        'const ops = new Receiver({ name: "ops", ...opsUntyped });',
+      ].join("\n"),
+    );
+    expect(files["settings.ts"]).toContain("// global: pigeon_loft is not a field Alertmanager v0.34.1 defines");
+    expect(files["settings.ts"]).toContain("...globalUntyped,");
+  });
+});
+
+describe("tsLiteral", () => {
+  test("multi-line strings are template literals with backticks, backslashes and ${ escaped", () => {
+    expect(tsLiteral("a\n`b` \\d ${x}", 0)).toBe("`a\n\\`b\\` \\\\d \\${x}`");
+  });
+
+  test("a string with double quotes is single-quoted, and keys that are not identifiers are quoted", () => {
+    expect(tsLiteral({ "a-b": 'x="1"', continue: true }, 0)).toBe(`{ "a-b": 'x="1"', continue: true }`);
+  });
+});
+
+test("PrometheusGenerator never hands core an empty file list", () => {
+  expect(new PrometheusGenerator().generate({ resources: [], parameters: [] })).toHaveLength(1);
+});
+
+test("an Slo's variable leaves its member's name, <name>Rules, free", async () => {
+  const { Slo } = await import("../composites/slo");
+  const { ruleGroupConfig } = await import("../rules");
+  const slo = ruleGroupConfig(
+    Slo({ name: "checkout", objective: 0.99, window: "30d", sli: { errors: "sum(rate(e[{{window}}]))", total: "sum(rate(t[{{window}}]))" } }).rules,
+  );
+  const files = byPath(generateRuleFileFiles({ groups: [{ name: "checkout-rules", rules: [] }, slo] }));
+  expect(files["slos.ts"]).toContain("const checkout = Slo({");
+  expect(files["rules.ts"]).toContain("const checkoutRulesGroup = new RuleGroup(");
+});