@intentius/chant-lexicon-prometheus 0.101.0 → 0.102.0

package/src/import/embedded.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, test } from "vitest";
 import { embeddedDocument, type EmbeddedContent } from "@intentius/chant/import/embedded";
 import { prometheusPlugin } from "../plugin";
-import { ruleGroupsImporter } from "./embedded";
+import { alertmanagerImporter, ruleGroupsImporter } from "./embedded";
 
 const GROUPS = [
   { name: "api", rules: [{ alert: "ApiDown", expr: "up{job=\"api\"} == 0", for: "5m" }] },
@@ -25,8 +25,8 @@ const site = (over: Partial<EmbeddedContent>): EmbeddedContent => ({
 });
 
 describe("rule groups embedded in another lexicon's resource (#2962)", () => {
-  test("the plugin registers the importer", () => {
-    expect(prometheusPlugin.embeddedImporters?.()).toEqual([ruleGroupsImporter]);
+  test("the plugin registers the importers", () => {
+    expect(prometheusPlugin.embeddedImporters?.()).toEqual([ruleGroupsImporter, alertmanagerImporter]);
   });
 
   test("matches a PrometheusRule's groups and a rule file held as text; not an alertmanager.yml", () => {
@@ -54,3 +54,52 @@ describe("rule groups embedded in another lexicon's resource (#2962)", () => {
     expect(out.value.bindings).toEqual([{ from: "rules.ts", name: "api" }]);
   });
 });
+
+const ALERTMANAGER = `route:
+  receiver: team
+  routes:
+    - matchers: [severity="critical"]
+      receiver: pager
+      mute_time_intervals: [nights]
+receivers:
+  - name: team
+  - name: pager
+time_intervals:
+  - name: nights
+    time_intervals:
+      - times: [{ start_time: "22:00", end_time: "24:00" }]
+inhibit_rules:
+  - source_matchers: [severity="critical"]
+    target_matchers: [severity="warning"]
+templates: [/etc/alertmanager/*.tmpl]
+`;
+
+describe("an alertmanager.yml embedded in another lexicon's resource (#3031)", () => {
+  const configMap = (text: string) =>
+    site({ hostType: "K8s::Core::ConfigMap", location: 'ConfigMap am data["alertmanager.yml"]', text, document: embeddedDocument(text) });
+
+  test("matches an alertmanager.yml held as text; not a rule file, nor a selected member", () => {
+    expect(alertmanagerImporter.matches(configMap(ALERTMANAGER))).toBe(true);
+    expect(alertmanagerImporter.matches(configMap(RULE_FILE))).toBe(false);
+    expect(alertmanagerImporter.matches(site({ document: { groups: GROUPS }, select: "groups" }))).toBe(false);
+    expect(ruleGroupsImporter.matches(configMap(ALERTMANAGER))).toBe(false);
+  });
+
+  test("becomes alertmanagerYaml over every declaration the standalone import writes", () => {
+    const out = alertmanagerImporter.import(configMap(ALERTMANAGER));
+    expect(out.files.map((f) => f.path)).toEqual(["receivers.ts", "time-intervals.ts", "routes.ts", "inhibit-rules.ts", "settings.ts"]);
+    expect(out.value).toEqual({
+      bindings: [
+        { from: "receivers.ts", name: "team" },
+        { from: "receivers.ts", name: "pager" },
+        { from: "time-intervals.ts", name: "nights" },
+        { from: "routes.ts", name: "root" },
+        { from: "inhibit-rules.ts", name: "inhibitRule1" },
+        { from: "settings.ts", name: "settings" },
+      ],
+      shape: "list",
+      through: { from: "@intentius/chant-lexicon-prometheus", name: "alertmanagerYaml" },
+    });
+    expect(out.warnings).toEqual([]);
+  });
+});

package/src/import/embedded.ts

@@ -1,19 +1,27 @@
 /**
- * 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.
+ * Prometheus and Alertmanager content embedded in another lexicon's
+ * resource, for `chant import`: a k8s `PrometheusRule`'s `spec.groups`, or a
+ * rule file held as text in a ConfigMap (#2962), and an `alertmanager.yml`
+ * held as text in a ConfigMap (#3031).
  *
  * 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.
+ *
+ * An `alertmanager.yml` is imported exactly as `chant import alertmanager.yml`
+ * would import it, and becomes `alertmanagerYaml([...])` over every receiver,
+ * time interval, root route, inhibit rule and settings it declares. The
+ * ConfigMap then holds the config as the serializer writes it: the same
+ * config, with Alertmanager's deprecated spellings rewritten as the
+ * standalone import rewrites them.
  */
 
 import type { EmbeddedContentImporter, EmbeddedImport } from "@intentius/chant/import/embedded";
-import { looksLikeRuleFile } from "../model";
+import { looksLikeAlertmanagerConfig, looksLikeRuleFile } from "../model";
 import { parsePrometheusYaml } from "./parser";
-import { generateRuleFile } from "./generator";
+import { generateAlertmanager, generateRuleFile } from "./generator";
 
 const PACKAGE = "@intentius/chant-lexicon-prometheus";
 
@@ -42,3 +50,27 @@ export const ruleGroupsImporter: EmbeddedContentImporter = {
     };
   },
 };
+
+export const alertmanagerImporter: EmbeddedContentImporter = {
+  what: "an Alertmanager config",
+
+  matches(content) {
+    return content.select === undefined && typeof content.text === "string" && looksLikeAlertmanagerConfig(content.document);
+  },
+
+  import(content): EmbeddedImport {
+    const parsed = parsePrometheusYaml(content.text!);
+    if (parsed.kind !== "alertmanager") throw new Error("this is not an alertmanager.yml");
+    const { files, declarations } = generateAlertmanager(parsed.config);
+    if (declarations.length === 0) throw new Error("the import declared nothing");
+    return {
+      files,
+      value: {
+        bindings: declarations.map((d) => ({ from: d.path, name: d.name })),
+        shape: "list",
+        through: { from: PACKAGE, name: "alertmanagerYaml" },
+      },
+      warnings: parsed.warnings,
+    };
+  },
+};

package/src/import/generator.ts

@@ -381,6 +381,21 @@ function untypedComment(what: string, keys: string[]): string[] {
 
 /** Generate the TypeScript declaring one `alertmanager.yml`. */
 export function generateAlertmanagerFiles(config: AlertmanagerConfig): GeneratedFile[] {
+  return generateAlertmanager(config).files;
+}
+
+/** A declaration an `alertmanager.yml` import exports: its module and variable. */
+export interface AlertmanagerDeclaration {
+  readonly path: string;
+  readonly name: string;
+}
+
+/**
+ * Generate the TypeScript declaring one `alertmanager.yml`, and list every
+ * declaration it exports, module by module (#3031: a ConfigMap holding the
+ * file becomes `alertmanagerYaml([...])` over them).
+ */
+export function generateAlertmanager(config: AlertmanagerConfig): { files: GeneratedFile[]; declarations: AlertmanagerDeclaration[] } {
   const names = new Names([...LEXICON_NAMES, "global", "tracing"]);
   const modules: Module[] = [];
   const receiverVars = new Map<string, { v: string; mod: Module }>();
@@ -558,7 +573,10 @@ export function generateAlertmanagerFiles(config: AlertmanagerConfig): Generated
     mod.exports.push(v);
   }
 
-  return modules.map((m) => ({ path: m.path, content: m.render() }));
+  return {
+    files: modules.map((m) => ({ path: m.path, content: m.render() })),
+    declarations: modules.flatMap((m) => m.exports.map((name) => ({ path: m.path, name }))),
+  };
 }
 
 /** The rule file and `alertmanager.yml` TypeScript generator `chant import` runs. */

package/src/lint/audit-catalog.ts

@@ -9,7 +9,8 @@
  * listed for a reader who meets them in a lint report.
  */
 
-import { auditRule, type RuleMeta } from "@intentius/chant/audit/catalog";
+import { applyLineage, auditRule, type RuleMeta } from "@intentius/chant/audit/catalog";
+import { prometheusAuditLineage } from "./audit-lineage";
 
 function sourceRule(id: string, category: RuleMeta["category"], title: string, remediation: string): RuleMeta {
   return { id, tier: "merge-worthy", fixKind: "guidance", category, title, remediation, yamlBased: false };
@@ -118,6 +119,16 @@ export const prometheusAuditCatalog: Record<string, RuleMeta> = {
     "merge-worthy",
     "correctness",
     "Receiver integration missing its destination or credential",
-    "Set the integration's url, api_url, routing_key or to/smarthost/from (or their *_file and global equivalents).",
+    "Set the integration's destination and credential (url, webhook_url, api_key, routing_key, chat_id, room_id, to/smarthost/from, ...), through its *_file or global equivalent where there is one.",
+  ),
+  PROM210: outputRule(
+    "PROM210",
+    "merge-worthy",
+    "correctness",
+    "Integration or global setting Alertmanager rejects",
+    "Set one of each value and its *_file, and use a value Alertmanager allows (e.g. message_type text or markdown, parse_mode Markdown, MarkdownV2 or HTML).",
   ),
 };
+
+// Prior art credits live beside the rules in ./audit-lineage.ts (see core audit/prior-art.ts).
+applyLineage(prometheusAuditCatalog, prometheusAuditLineage);

package/src/lint/audit-lineage.ts

@@ -0,0 +1,69 @@
+/**
+ * Prior art for the prometheus lexicon's audit rules: the tools whose checks
+ * cover the same condition, credited per rule. See
+ * packages/core/src/audit/prior-art.ts for the registry, the relation
+ * vocabulary, and why this is credit rather than authority. Kept by hand.
+ *
+ * Mapped against each tool's own check list (#2916):
+ *
+ * - promtool check rules parses a rule file with Prometheus's rulefmt
+ *   package (model/rulefmt/rulefmt.go): repeated group names, record/alert
+ *   exclusivity, annotations/for/keep_firing_for on recording rules, durations,
+ *   and PromQL syntax. It has no per-rule ids, so those credits omit `rule`.
+ * - amtool check-config loads an Alertmanager config with the same code the
+ *   server uses (config/config.go): undefined receivers and time intervals,
+ *   non-unique names, a root route that is missing, has no receiver or has
+ *   matchers, matcher syntax, durations, missing integration destinations and
+ *   credentials, and "at most one of X and X_file". No per-rule ids either.
+ * - pint (cloudflare/pint, docs/checks/) is a rule linter with named checks.
+ *   promql/syntax, rule/duplicate, rule/label, alerts/annotation and
+ *   alerts/for map onto chant rules. rule/label and alerts/annotation are
+ *   configurable "this label or annotation must exist" checks that pint ships
+ *   with nothing enabled, so they overlap PROM106 and PROM107 and no more.
+ *
+ * Deliberately without a credit from these tools:
+ * - PROM001 and PROM003: a literal credential in TypeScript source, and the
+ *   Slo objective/window model. Neither tool reads either.
+ * - PROM202 (severity not routed) and PROM207 (receiver never routed to):
+ *   check-config accepts both, and `amtool config routes test` answers a
+ *   different question (where one given label set goes).
+ */
+import type { Lineage } from "@intentius/chant/audit/catalog";
+
+const RULEFMT = "https://github.com/prometheus/prometheus/blob/main/model/rulefmt/rulefmt.go";
+const AM_CONFIG = "https://github.com/prometheus/alertmanager/blob/main/config/config.go";
+const PINT = "https://github.com/cloudflare/pint/blob/main/docs/checks";
+
+const amtool = (relation: Lineage["relation"]): Lineage => ({
+  tool: "amtool",
+  url: AM_CONFIG,
+  relation,
+});
+
+export const prometheusAuditLineage: Record<string, Lineage[]> = {
+  PROM002: [
+    { tool: "promtool", url: RULEFMT, relation: "equivalent" },
+    { tool: "pint", rule: "promql/syntax", url: `${PINT}/promql/syntax.md`, relation: "equivalent" },
+  ],
+  PROM101: [{ tool: "promtool", url: RULEFMT, relation: "equivalent" }],
+  PROM102: [{ tool: "pint", rule: "rule/duplicate", url: `${PINT}/rule/duplicate.md`, relation: "overlaps" }],
+  PROM103: [
+    { tool: "promtool", url: RULEFMT, relation: "equivalent" },
+    { tool: "pint", rule: "alerts/for", url: `${PINT}/alerts/for.md`, relation: "overlaps" },
+  ],
+  PROM104: [
+    { tool: "promtool", url: RULEFMT, relation: "equivalent" },
+    { tool: "pint", rule: "promql/syntax", url: `${PINT}/promql/syntax.md`, relation: "equivalent" },
+  ],
+  PROM105: [{ tool: "promtool", url: RULEFMT, relation: "equivalent" }],
+  PROM106: [{ tool: "pint", rule: "rule/label", url: `${PINT}/rule/label.md`, relation: "overlaps" }],
+  PROM107: [{ tool: "pint", rule: "alerts/annotation", url: `${PINT}/alerts/annotation.md`, relation: "overlaps" }],
+  PROM201: [amtool("equivalent")],
+  PROM203: [amtool("equivalent")],
+  PROM204: [amtool("equivalent")],
+  PROM205: [amtool("equivalent")],
+  PROM206: [amtool("equivalent")],
+  PROM208: [amtool("equivalent")],
+  PROM209: [amtool("overlaps")],
+  PROM210: [amtool("overlaps")],
+};

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

@@ -16,6 +16,7 @@ import { prom206 } from "./prom206";
 import { prom207 } from "./prom207";
 import { prom208 } from "./prom208";
 import { prom209 } from "./prom209";
+import { prom210 } from "./prom210";
 
 export const postSynthChecks: PostSynthCheck[] = [
   prom101,
@@ -34,4 +35,5 @@ export const postSynthChecks: PostSynthCheck[] = [
   prom207,
   prom208,
   prom209,
+  prom210,
 ];

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

@@ -1,6 +1,8 @@
 import { describe, expect, test } from "vitest";
 import { makePostSynthCtx, makePostSynthCtxFromFiles } from "@intentius/chant-test-utils";
 import { postSynthChecks } from "./index";
+import { RECEIVER_INTEGRATION_TYPES } from "../../integrations";
+import { INTEGRATION_CASES, SLACK_APP_URL, amWith } from "../../testdata/integration-cases";
 import { prom101 } from "./prom101";
 import { prom102 } from "./prom102";
 import { prom103 } from "./prom103";
@@ -17,6 +19,7 @@ import { prom206 } from "./prom206";
 import { prom207 } from "./prom207";
 import { prom208 } from "./prom208";
 import { prom209 } from "./prom209";
+import { prom210 } from "./prom210";
 
 const RULES = `groups:
   - name: api
@@ -245,6 +248,37 @@ receivers:
   });
 });
 
+const integrationCodes = (text: string) =>
+  [prom208, prom209, prom210].flatMap((c) => c.check(amOnly(text))).map((d) => d.checkId).sort();
+
+describe("PROM208-PROM210 on every Alertmanager integration", () => {
+  test.each(INTEGRATION_CASES)("%s", (_label, key, entry, global, codes) => {
+    expect(integrationCodes(amWith(key, entry, global))).toEqual(codes);
+  });
+
+  test("every integration has a passing and a failing case", () => {
+    for (const key of Object.keys(RECEIVER_INTEGRATION_TYPES)) {
+      const cases = INTEGRATION_CASES.filter((c) => c[1] === key);
+      expect(cases.some((c) => c[4].length === 0), `${key} passing`).toBe(true);
+      expect(cases.some((c) => c[4].length > 0), `${key} failing`).toBe(true);
+    }
+  });
+
+  test("findings name the receiver and the entry", () => {
+    const [d] = prom209.check(amOnly(amWith("opsgenie_configs", {})));
+    expect(d).toMatchObject({ checkId: "PROM209", severity: "error", entity: "r" });
+    expect(d.message).toContain('receiver "r" opsgenie_configs[0] has no api_key');
+  });
+
+  test("PROM210 and PROM208 in global", () => {
+    const am = (global: Record<string, unknown>) => JSON.stringify({ global, route: { receiver: "r" }, receivers: [{ name: "r" }] });
+    expect(integrationCodes(am({ slack_app_token_file: "/t", slack_api_url: "https://hooks.slack.com/x" }))).toEqual(["PROM210"]);
+    expect(integrationCodes(am({ slack_app_token_file: "/t", slack_api_url: SLACK_APP_URL }))).toEqual([]);
+    expect(integrationCodes(am({ smtp_auth_password: "x", smtp_auth_password_file: "/p", smtp_smarthost: "smtp" }))).toEqual(["PROM210", "PROM210"]);
+    expect(integrationCodes(am({ resolve_timeout: "1.5m" }))).toEqual(["PROM208"]);
+  });
+});
+
 describe("documents from other lexicons", () => {
   test("a k8s manifest and a collector config are not read as ours", () => {
     const ctx = makePostSynthCtx(

package/src/lint/post-synth/prom-helpers.ts

@@ -71,7 +71,7 @@ export function ruleFileDiagnostics(ctx: PostSynthContext, code: PrometheusIssue
   );
 }
 
-/** Diagnostics for one Alertmanager code (PROM201, PROM203-PROM209) across every `alertmanager.yml` in the output. */
+/** Diagnostics for one Alertmanager code (PROM201, PROM203-PROM210) across every `alertmanager.yml` in the output. */
 export function alertmanagerDiagnostics(ctx: PostSynthContext, code: PrometheusIssueCode): PostSynthDiagnostic[] {
   return prometheusDocs(ctx).alertmanager.flatMap(({ source, config }) =>
     validateAlertmanagerConfig(config)

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

@@ -1,7 +1,7 @@
 /**
  * PROM208: An Alertmanager duration is not a duration
  *
- * group_wait, group_interval, repeat_interval, resolve_timeout and webhook timeout take durations such as 30s or 4h.
+ * group_wait, group_interval, repeat_interval, resolve_timeout and Jira reopen_duration take Prometheus durations (30s, 4h, 1d); the timeout of webhook, Slack, PagerDuty and incident.io, and Pushover retry, expire and ttl take Go durations (10s, 1m30s, 500ms).
  */
 
 import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";

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

@@ -1,7 +1,7 @@
 /**
  * PROM209: A receiver integration is missing its destination or credential
  *
- * A webhook needs url or url_file, Slack an api_url (or the global one), PagerDuty a routing_key or service_key, and email a to address, a smarthost and a from address (or their global defaults).
+ * Every one of Alertmanager's 18 integrations is checked for the destination, credential and required fields its config validation asks for, with the global defaults it falls back to: e.g. a webhook url, an Opsgenie api_key (or global.opsgenie_api_key), a Telegram chat_id and bot token, a Webex room_id and authorization, an SNS target, a Jira project and issue_type.
  */
 
 import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";

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

@@ -0,0 +1,17 @@
+/**
+ * PROM210: A receiver integration or global setting is one Alertmanager rejects
+ *
+ * Two settings that exclude each other (a value and its *_file, a Slack api_url and app_token, Pushover html and monospace, two SNS targets), or a value outside the allowed set (WeChat message_type, Telegram parse_mode, Jira api_type, an Opsgenie responder type, a VictorOps reserved custom field, a smarthost that is not host:port, a Slack or Mattermost field without title and value).
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { alertmanagerDiagnostics } from "./prom-helpers";
+
+export const prom210: PostSynthCheck = {
+  id: "PROM210",
+  description: "A receiver integration or global setting is one Alertmanager rejects",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return alertmanagerDiagnostics(ctx, "PROM210");
+  },
+};

package/src/plugin.test.ts

@@ -37,6 +37,7 @@ describe("prometheus plugin", () => {
       "PROM207",
       "PROM208",
       "PROM209",
+      "PROM210",
     ]);
   });
 

package/src/plugin.ts

@@ -11,7 +11,7 @@ import { hover } from "./lsp/hover";
 import { detectTemplate } from "./detect";
 import { PrometheusParser } from "./import/parser";
 import { PrometheusGenerator } from "./import/generator";
-import { ruleGroupsImporter } from "./import/embedded";
+import { alertmanagerImporter, ruleGroupsImporter } from "./import/embedded";
 import { DEFAULT_TEMPLATE, RULES_TEMPLATE, SLO_STYLE_TEMPLATE, SLO_TEMPLATE } from "./init-templates";
 import { prometheusSkills } from "./skill-defs";
 import { CATALOG } from "./catalog";
@@ -122,7 +122,7 @@ export const prometheusPlugin: LexiconPlugin = {
   },
 
   embeddedImporters() {
-    return [ruleGroupsImporter];
+    return [ruleGroupsImporter, alertmanagerImporter];
   },
 
   // `chant init --lexicon prometheus [--template rules|slo-style|slo]`; see ./init-templates.ts.

package/src/skills/chant-prometheus-alertmanager.md

@@ -57,6 +57,8 @@ Import it rather than retyping it: `chant import alertmanager.yml --output src`
 - Routes name receivers and time intervals that exist (PROM201, PROM204). Reference the entity rather than a string and TypeScript does most of this.
 - Every `severity` an alert in the same build root carries is matched by some route below the root (PROM202). The check only sees one build root (chant #1939): keep the rules and the Alertmanager config in the same one, or it goes quiet.
 - Credentials go in `*_file` fields. Alertmanager does not expand environment variables in its config, and a literal `api_url`, `routing_key` or `auth_password` is flagged (PROM001).
-- Each integration has somewhere to send (PROM209): a webhook `url`, a Slack `api_url` (or `global.slack_api_url`), a PagerDuty key, an email `to`/`smarthost`/`from` (or the global SMTP defaults).
+- Each integration has its destination, credential and required fields, or the `global` default it falls back to (PROM209): a webhook `url`, a Slack `api_url` or app token, an Opsgenie `api_key`, a Telegram `chat_id` and bot token, a Webex `room_id` and `http_config.authorization`, one SNS target, a Jira `project` and `issue_type`, an email `to`/`smarthost`/`from`, and so on.
+- No setting Alertmanager rejects (PROM210): a value and its `*_file` both set, a Slack `api_url` with an app token, `update_message` without `api_url: https://slack.com/api/chat.postMessage`, a WeChat `message_type` other than `text`/`markdown`, a Telegram `parse_mode` other than `Markdown`/`MarkdownV2`/`HTML`.
+- Durations parse (PROM208). Route timers and `resolve_timeout` take `1d`; the integration `timeout`s and Pushover `retry`/`expire`/`ttl` are Go durations and take `24h`, not `1d`.
 
 Run `amtoolCheckConfig(alertmanagerYaml(entities))` in a test to have `amtool check-config` confirm it when installed.

package/src/testdata/integration-cases.ts

@@ -0,0 +1,96 @@
+/**
+ * Alertmanager receiver integrations that pass and fail PROM208-PROM210: at
+ * least one of each per integration, after Alertmanager v0.34.1's
+ * UnmarshalYAML validations (sources in ../validate-integrations.ts).
+ * post-synth.test.ts checks the codes; tools.test.ts has amtool reject the
+ * failing ones when it is installed.
+ *
+ * Each case: a label, the receiver key, one entry, an optional `global:`,
+ * and the PROM208-PROM210 codes it produces, sorted.
+ */
+
+export type IntegrationCase = [label: string, key: string, entry: Record<string, unknown>, global: Record<string, unknown> | undefined, codes: string[]];
+const PD = "https://events.pagerduty.com/v2/enqueue";
+export const SLACK_APP_URL = "https://slack.com/api/chat.postMessage";
+export const INTEGRATION_CASES: IntegrationCase[] = [
+  ["discord ok", "discord_configs", { webhook_url_file: "/s" }, undefined, []],
+  ["discord without a webhook", "discord_configs", {}, undefined, ["PROM209"]],
+  ["discord with url and file", "discord_configs", { webhook_url: "https://d/x", webhook_url_file: "/s" }, undefined, ["PROM210"]],
+  ["email ok", "email_configs", { to: "a@b.c", from: "am@b.c", smarthost: "smtp:25" }, undefined, []],
+  ["email on global SMTP", "email_configs", { to: "a@b.c" }, { smtp_smarthost: "smtp:25", smtp_from: "am@b.c" }, []],
+  ["email with nothing", "email_configs", {}, undefined, ["PROM209", "PROM209", "PROM209"]],
+  ["email smarthost without port", "email_configs", { to: "a@b.c", from: "am@b.c", smarthost: "smtp" }, undefined, ["PROM210"]],
+  ["email duplicate header", "email_configs", { to: "a@b.c", from: "f@b.c", smarthost: "s:25", headers: { subject: "a", Subject: "b" } }, undefined, ["PROM210"]],
+  ["email threading without thread_by_date", "email_configs", { to: "a@b.c", from: "f@b.c", smarthost: "s:25", threading: { enabled: true } }, undefined, ["PROM210"]],
+  ["email threading with References", "email_configs", { to: "a@b.c", from: "f@b.c", smarthost: "s:25", headers: { references: "x" }, threading: { enabled: true, thread_by_date: "daily" } }, undefined, ["PROM210"]],
+  ["incident.io ok", "incidentio_configs", { url: "https://i/x", alert_source_token_file: "/t", timeout: "1.5s" }, undefined, []],
+  ["incident.io without url", "incidentio_configs", {}, undefined, ["PROM209"]],
+  ["incident.io http_config without a credential", "incidentio_configs", { url: "https://i/x", http_config: { follow_redirects: true } }, undefined, ["PROM209"]],
+  ["incident.io token and authorization", "incidentio_configs", { url: "https://i/x", alert_source_token_file: "/t", http_config: { authorization: { credentials_file: "/c" } } }, undefined, ["PROM210"]],
+  ["incident.io Prometheus-only duration", "incidentio_configs", { url_file: "/u", timeout: "1d" }, undefined, ["PROM208"]],
+  ["jira ok", "jira_configs", { api_url: "https://j/x", project: "OPS", issue_type: "Bug", reopen_duration: "1d" }, undefined, []],
+  ["jira on global api_url", "jira_configs", { project: "OPS", issue_type: "Bug" }, { jira_api_url: "https://j/x" }, []],
+  ["jira with nothing", "jira_configs", {}, undefined, ["PROM209", "PROM209", "PROM209"]],
+  ["jira api_type", "jira_configs", { api_url: "https://j/x", project: "OPS", issue_type: "Bug", api_type: "server" }, undefined, ["PROM210"]],
+  ["jira Go-only duration", "jira_configs", { api_url: "https://j/x", project: "OPS", issue_type: "Bug", reopen_duration: "1.5h" }, undefined, ["PROM208"]],
+  ["mattermost ok", "mattermost_configs", { webhook_url_file: "/m" }, undefined, []],
+  ["mattermost on global webhook", "mattermost_configs", {}, { mattermost_webhook_url_file: "/m" }, []],
+  ["mattermost without a webhook", "mattermost_configs", {}, undefined, ["PROM209"]],
+  ["mattermost field without value", "mattermost_configs", { webhook_url_file: "/m", attachments: [{ fields: [{ title: "a" }] }] }, undefined, ["PROM210"]],
+  ["msteams ok", "msteams_configs", { webhook_url_file: "/t" }, undefined, []],
+  ["msteams without a webhook", "msteams_configs", {}, undefined, ["PROM209"]],
+  ["msteamsv2 ok", "msteamsv2_configs", { webhook_url_file: "/t" }, undefined, []],
+  ["msteamsv2 with url and file", "msteamsv2_configs", { webhook_url: "https://t/x", webhook_url_file: "/t" }, undefined, ["PROM210"]],
+  ["opsgenie ok", "opsgenie_configs", { api_key_file: "/k", responders: [{ name: "ops", type: "Team" }, { id: "1", type: "{{ .CommonLabels.kind }}" }] }, undefined, []],
+  ["opsgenie on global api_key", "opsgenie_configs", {}, { opsgenie_api_key_file: "/k" }, []],
+  ["opsgenie without api_key", "opsgenie_configs", {}, undefined, ["PROM209"]],
+  ["opsgenie responders", "opsgenie_configs", { api_key_file: "/k", responders: [{ type: "team" }, { name: "x", type: "group" }, { name: "y" }] }, undefined, ["PROM209", "PROM209", "PROM210"]],
+  ["pagerduty ok", "pagerduty_configs", { routing_key_file: "/k", url: PD, timeout: "30s" }, undefined, []],
+  ["pagerduty without a key", "pagerduty_configs", {}, undefined, ["PROM209"]],
+  ["pagerduty key and file", "pagerduty_configs", { service_key: "x", service_key_file: "/k" }, undefined, ["PROM210"]],
+  ["pagerduty timeout without unit", "pagerduty_configs", { routing_key_file: "/k", timeout: "10" }, undefined, ["PROM208"]],
+  ["pushover ok", "pushover_configs", { user_key_file: "/u", token_file: "/t", retry: "30s", expire: "1h", ttl: "1h30m" }, undefined, []],
+  ["pushover without credentials", "pushover_configs", {}, undefined, ["PROM209", "PROM209"]],
+  ["pushover html and monospace", "pushover_configs", { user_key_file: "/u", token_file: "/t", html: true, monospace: true }, undefined, ["PROM210"]],
+  ["pushover retry in days", "pushover_configs", { user_key_file: "/u", token_file: "/t", retry: "1d" }, undefined, ["PROM208"]],
+  ["rocketchat ok", "rocketchat_configs", { token_id_file: "/i", token_file: "/t" }, undefined, []],
+  ["rocketchat on global tokens", "rocketchat_configs", {}, { rocketchat_token_id_file: "/i", rocketchat_token_file: "/t" }, []],
+  ["rocketchat without tokens", "rocketchat_configs", {}, undefined, ["PROM209", "PROM209"]],
+  ["rocketchat token and file", "rocketchat_configs", { token_id_file: "/i", token: "x", token_file: "/t" }, undefined, ["PROM210"]],
+  ["slack ok", "slack_configs", { api_url_file: "/s", timeout: "500ms" }, undefined, []],
+  ["slack on global app token", "slack_configs", {}, { slack_app_token_file: "/t" }, []],
+  ["slack update_message with the app URL", "slack_configs", { api_url: SLACK_APP_URL, update_message: true, http_config: { authorization: { credentials_file: "/t" } } }, undefined, []],
+  ["slack without a url or token", "slack_configs", { channel: "#a" }, undefined, ["PROM209"]],
+  ["slack local authorization blocks the global token", "slack_configs", { http_config: { authorization: { credentials_file: "/t" } } }, { slack_app_token_file: "/t" }, ["PROM209"]],
+  ["slack url and token", "slack_configs", { api_url_file: "/s", app_token_file: "/t" }, undefined, ["PROM210"]],
+  ["slack update_message on a webhook", "slack_configs", { api_url_file: "/s", update_message: true }, undefined, ["PROM210"]],
+  ["slack app token and authorization", "slack_configs", { app_token_file: "/t", http_config: { bearer_token_file: "/b" } }, undefined, ["PROM210"]],
+  ["slack fields and actions", "slack_configs", { api_url_file: "/s", fields: [{ title: "a" }], actions: [{ type: "button", text: "x" }, { type: "button", text: "y", name: "n", confirm: {} }] }, undefined, ["PROM210", "PROM210", "PROM210"]],
+  ["slack timeout", "slack_configs", { api_url_file: "/s", timeout: "5 s" }, undefined, ["PROM208"]],
+  ["sns ok", "sns_configs", { topic_arn: "arn:aws:sns:x" }, undefined, []],
+  ["sns without a target", "sns_configs", {}, undefined, ["PROM209"]],
+  ["sns with two targets", "sns_configs", { topic_arn: "arn:aws:sns:x", target_arn: "arn:aws:sns:y" }, undefined, ["PROM210"]],
+  ["telegram ok", "telegram_configs", { bot_token_file: "/t", chat_id: 12, parse_mode: "MarkdownV2" }, undefined, []],
+  ["telegram on global bot token", "telegram_configs", { chat_id_file: "/c" }, { telegram_bot_token_file: "/t" }, []],
+  ["telegram with nothing", "telegram_configs", {}, undefined, ["PROM209", "PROM209"]],
+  ["telegram chat_id and file, bad parse_mode", "telegram_configs", { bot_token_file: "/t", chat_id: 12, chat_id_file: "/c", parse_mode: "markdown" }, undefined, ["PROM210", "PROM210"]],
+  ["victorops ok", "victorops_configs", { routing_key: "ops", api_key_file: "/k" }, undefined, []],
+  ["victorops on global api_key", "victorops_configs", { routing_key: "ops" }, { victorops_api_key_file: "/k" }, []],
+  ["victorops with nothing", "victorops_configs", {}, undefined, ["PROM209", "PROM209"]],
+  ["victorops reserved custom field", "victorops_configs", { routing_key: "ops", api_key_file: "/k", custom_fields: { entity_id: "x" } }, undefined, ["PROM210"]],
+  ["webex ok", "webex_configs", { room_id: "r", http_config: { bearer_token_file: "/t" } }, undefined, []],
+  ["webex with nothing", "webex_configs", {}, undefined, ["PROM209", "PROM209"]],
+  ["webex with only a global authorization", "webex_configs", { room_id: "r" }, { http_config: { authorization: { credentials_file: "/t" } } }, ["PROM209"]],
+  ["webhook ok", "webhook_configs", { url: "http://sink/", timeout: "1m30s" }, undefined, []],
+  ["webhook without url", "webhook_configs", {}, undefined, ["PROM209"]],
+  ["webhook url and file", "webhook_configs", { url: "http://sink/", url_file: "/u" }, undefined, ["PROM210"]],
+  ["webhook timeout in days", "webhook_configs", { url: "http://sink/", timeout: "1d" }, undefined, ["PROM208"]],
+  ["wechat ok", "wechat_configs", { api_secret_file: "/s", corp_id: "c", message_type: "markdown" }, undefined, []],
+  ["wechat on global secret and corp", "wechat_configs", {}, { wechat_api_secret_file: "/s", wechat_api_corp_id: "c" }, []],
+  ["wechat with nothing", "wechat_configs", {}, undefined, ["PROM209", "PROM209"]],
+  ["wechat message_type", "wechat_configs", { api_secret_file: "/s", corp_id: "c", message_type: "html" }, undefined, ["PROM210"]],
+];
+
+/** An `alertmanager.yml`, as JSON, with one receiver `r` holding `entry` under `key`. */
+export const amWith = (key: string, entry: unknown, global?: Record<string, unknown>): string =>
+  JSON.stringify({ ...(global ? { global } : {}), route: { receiver: "r" }, receivers: [{ name: "r", [key]: [entry] }] });

package/src/tools.test.ts

@@ -17,6 +17,7 @@ import {
   promtoolCheckRules,
   ruleFileYaml,
 } from "./index";
+import { INTEGRATION_CASES, amWith } from "./testdata/integration-cases";
 
 const PROMTOOL = process.env.PROMTOOL ?? "promtool";
 const AMTOOL = process.env.AMTOOL ?? "amtool";
@@ -113,6 +114,11 @@ describe("amtool check-config", () => {
     expect(r.ok).toBe(false);
   });
 
+  test.skipIf(!hasAmtool).each(INTEGRATION_CASES.filter((c) => c[4].length > 0))("rejects what PROM208-PROM210 flag: %s", (_label, key, entry, global) => {
+    const r = amtoolCheckConfig(amWith(key, entry, global), AMTOOL);
+    expect(r.ok, r.output).toBe(false);
+  });
+
   test("reports ran: false when the binary is missing", () => {
     expect(amtoolCheckConfig("route: {}\n", "/nonexistent/amtool").ran).toBe(false);
   });

package/src/validate-config.ts

@@ -20,6 +20,7 @@ import {
   type RuleGroupConfig,
 } from "./model";
 import { checkPromql } from "./promql";
+import { validateGlobalSettings, validateReceiverIntegrations } from "./validate-integrations";
 
 export type PrometheusIssueCode =
   | "PROM101"
@@ -37,7 +38,8 @@ export type PrometheusIssueCode =
   | "PROM206"
   | "PROM207"
   | "PROM208"
-  | "PROM209";
+  | "PROM209"
+  | "PROM210";
 
 export interface PrometheusIssue {
   code: PrometheusIssueCode;
@@ -221,7 +223,7 @@ function visitRoutes(root: RouteConfig | undefined): RouteVisit[] {
 
 const AM_DURATIONS = ["group_wait", "group_interval", "repeat_interval"] as const;
 
-/** Check an `alertmanager.yml` on its own (PROM201, PROM203-PROM209). */
+/** Check an `alertmanager.yml` on its own (PROM201, PROM203-PROM210). */
 export function validateAlertmanagerConfig(config: AlertmanagerConfig): PrometheusIssue[] {
   const issues: PrometheusIssue[] = [];
   const receivers = Array.isArray(config?.receivers) ? config.receivers : [];
@@ -307,41 +309,16 @@ export function validateAlertmanagerConfig(config: AlertmanagerConfig): Promethe
     }
   });
 
-  if (global.resolve_timeout !== undefined && !isValidDuration(global.resolve_timeout)) {
-    issues.push({ code: "PROM208", severity: "error", subject: "global", message: `global.resolve_timeout "${str(global.resolve_timeout)}" is not a duration` });
-  }
+  // PROM208, PROM210: global settings
+  issues.push(...validateGlobalSettings(global));
 
-  // PROM207: unused receivers; PROM209: incomplete integrations
+  // PROM207: unused receivers; PROM208-PROM210: integrations (./validate-integrations.ts)
   for (const r of receivers) {
     const name = str(r?.name ?? "");
     if (!usedReceivers.has(name)) {
       issues.push({ code: "PROM207", severity: "warning", subject: name, message: `receiver "${name}" is declared but no route sends to it` });
     }
-    for (const [i, w] of (r.webhook_configs ?? []).entries()) {
-      if (!w.url && !w.url_file) issues.push({ code: "PROM209", severity: "error", subject: name, message: `receiver "${name}" webhook_configs[${i}] has no url or url_file` });
-      if (w.timeout !== undefined && !isValidDuration(w.timeout)) {
-        issues.push({ code: "PROM208", severity: "error", subject: name, message: `receiver "${name}" webhook_configs[${i}].timeout "${str(w.timeout)}" is not a duration` });
-      }
-    }
-    for (const [i, s] of (r.slack_configs ?? []).entries()) {
-      if (!s.api_url && !s.api_url_file && !global.slack_api_url && !global.slack_api_url_file) {
-        issues.push({ code: "PROM209", severity: "error", subject: name, message: `receiver "${name}" slack_configs[${i}] has no api_url or api_url_file, and global sets no slack_api_url` });
-      }
-    }
-    for (const [i, p] of (r.pagerduty_configs ?? []).entries()) {
-      if (!p.routing_key && !p.routing_key_file && !p.service_key && !p.service_key_file) {
-        issues.push({ code: "PROM209", severity: "error", subject: name, message: `receiver "${name}" pagerduty_configs[${i}] has no routing_key(_file) or service_key(_file)` });
-      }
-    }
-    for (const [i, e] of (r.email_configs ?? []).entries()) {
-      if (!e.to) issues.push({ code: "PROM209", severity: "error", subject: name, message: `receiver "${name}" email_configs[${i}] has no to address` });
-      if (!e.smarthost && !global.smtp_smarthost) {
-        issues.push({ code: "PROM209", severity: "error", subject: name, message: `receiver "${name}" email_configs[${i}] has no smarthost, and global sets no smtp_smarthost` });
-      }
-      if (!e.from && !global.smtp_from) {
-        issues.push({ code: "PROM209", severity: "error", subject: name, message: `receiver "${name}" email_configs[${i}] has no from address, and global sets no smtp_from` });
-      }
-    }
+    issues.push(...validateReceiverIntegrations(r, global));
     // A receiver with no integrations at all is valid: it is how Alertmanager drops alerts.
   }