@intentius/chant-lexicon-prometheus 0.100.0 → 0.102.0

package/src/plugin.ts

@@ -11,8 +11,8 @@ 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 { initTemplates } from "./init-templates";
+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";
 import { PROMETHEUS_PIN } from "./pin";
@@ -122,11 +122,15 @@ export const prometheusPlugin: LexiconPlugin = {
   },
 
   embeddedImporters() {
-    return [ruleGroupsImporter];
+    return [ruleGroupsImporter, alertmanagerImporter];
   },
 
+  // `chant init --lexicon prometheus [--template rules|slo-style|slo]`; see ./init-templates.ts.
   initTemplates(template?: string) {
-    return initTemplates(template);
+    if (template === "rules") return RULES_TEMPLATE;
+    if (template === "slo-style") return SLO_STYLE_TEMPLATE;
+    if (template === "slo") return SLO_TEMPLATE;
+    return DEFAULT_TEMPLATE;
   },
 
   completionProvider(ctx: CompletionContext) {

package/src/rule-eval.ts

@@ -7,10 +7,15 @@
  * The PromQL it understands is the subset the lexicon's generated rules use:
  * number literals, vector and range selectors with `=`, `!=`, `=~` and `!~`
  * matchers, `rate`, `increase`, `avg_over_time`, `sum_over_time`,
- * `count_over_time`, `vector`, `sum` (with `by` or `without`), the
- * arithmetic and comparison operators and `and`, `or` and `unless` (with
- * `on` or `ignoring`). Anything else throws, so a test never passes by
- * silently evaluating something it does not understand.
+ * `count_over_time`, `vector`, `histogram_quantile`, `sum` (with `by` or
+ * `without`), the arithmetic and comparison operators (one-to-one, or
+ * many-to-one with `group_left` and no extra labels) and `and`, `or` and
+ * `unless` (with `on` or `ignoring`). Anything else throws, so a test never
+ * passes by silently evaluating something it does not understand.
+ *
+ * `histogram_quantile` interpolates linearly inside the bucket the rank
+ * falls in, as Prometheus does for classic buckets, and returns the upper
+ * bound of the highest finite bucket when the rank falls in `+Inf`.
  *
  * `rate` is the increase between the first and last sample in the range
  * over the time between them, without Prometheus's extrapolation to the
@@ -49,6 +54,7 @@ export interface FiringAlert {
 }
 
 const LOOKBACK_MS = 5 * 60_000;
+const RANGE_FUNCTIONS = new Set(["rate", "increase", "avg_over_time", "sum_over_time", "count_over_time"]);
 
 function key(labels: Labels): string {
   return JSON.stringify(Object.entries(labels).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
@@ -217,12 +223,15 @@ export class RuleEvaluator {
 
   private call(n: SyntaxNode, src: string, t: number): Value {
     const fn = this.text(n.getChild("FunctionIdentifier")!, src);
-    const [arg] = this.args(n.getChild("FunctionCallBody")!);
+    const [arg, second] = this.args(n.getChild("FunctionCallBody")!);
+    if (fn === "histogram_quantile") return this.histogramQuantile(arg, second, src, t);
     if (fn === "vector") {
       const v = this.node(arg, src, t);
       if (v.kind !== "scalar") throw new Error("rule-eval: vector() takes a scalar");
       return { kind: "vector", elements: [{ labels: {}, value: v.value }] };
     }
+    // Checked before any series is read, so an unsupported function throws even over no data.
+    if (!RANGE_FUNCTIONS.has(fn)) throw new Error(`rule-eval: function ${fn} is not supported`);
     if (arg.name !== "MatrixSelector") throw new Error(`rule-eval: ${fn}() needs a range selector`);
     const rangeMs = durationMs(this.text(arg.getChild("DurationExpr")!, src));
     if (rangeMs === undefined) throw new Error(`rule-eval: bad range in ${this.text(arg, src)}`);
@@ -254,6 +263,45 @@ export class RuleEvaluator {
     return { kind: "vector", elements };
   }
 
+  private histogramQuantile(qNode: SyntaxNode, vNode: SyntaxNode, src: string, t: number): Value {
+    const q = this.node(qNode, src, t);
+    const v = this.node(vNode, src, t);
+    if (q.kind !== "scalar" || v.kind !== "vector") throw new Error("rule-eval: histogram_quantile takes a scalar and a vector");
+    const groups = new Map<string, { labels: Labels; buckets: { le: number; count: number }[] }>();
+    for (const e of v.elements) {
+      const { le, ...rest } = withoutName(e.labels);
+      if (le === undefined) continue;
+      const k = key(rest);
+      const g = groups.get(k) ?? { labels: rest, buckets: [] };
+      g.buckets.push({ le: le === "+Inf" ? Infinity : Number(le), count: e.value });
+      groups.set(k, g);
+    }
+    const elements: VectorElement[] = [];
+    for (const { labels, buckets } of groups.values()) {
+      buckets.sort((a, b) => a.le - b.le);
+      const last = buckets[buckets.length - 1];
+      if (!last || last.le !== Infinity) continue;
+      const total = last.count;
+      let value: number;
+      if (q.value < 0) value = -Infinity;
+      else if (q.value > 1) value = Infinity;
+      else if (!(total > 0)) value = NaN;
+      else {
+        const rank = q.value * total;
+        const i = buckets.findIndex((b) => b.count >= rank);
+        if (buckets[i].le === Infinity) value = buckets.length > 1 ? buckets[buckets.length - 2].le : NaN;
+        else {
+          const start = i === 0 ? 0 : buckets[i - 1].le;
+          const below = i === 0 ? 0 : buckets[i - 1].count;
+          const inBucket = buckets[i].count - below;
+          value = inBucket > 0 ? start + (buckets[i].le - start) * ((rank - below) / inBucket) : buckets[i].le;
+        }
+      }
+      elements.push({ labels, value });
+    }
+    return { kind: "vector", elements };
+  }
+
   private aggregate(n: SyntaxNode, src: string, t: number): Value {
     const op = this.text(n.getChild("AggregateOp")!, src);
     if (op !== "sum") throw new Error(`rule-eval: aggregation ${op} is not supported`);
@@ -293,11 +341,20 @@ export class RuleEvaluator {
     if (parts.some((p) => p.name === "BoolModifier")) throw new Error("rule-eval: bool modifier is not supported");
     let on: string[] | undefined;
     let ignoring: string[] = [];
+    let groupLeft = false;
     if (modifier) {
-      const names = (modifier.getChild("GroupingLabels")?.getChildren("LabelName") ?? []).map((l) => this.text(l, src));
+      const grouping = modifier.getChild("GroupingLabels");
+      const names = (grouping?.getChildren("LabelName") ?? []).map((l) => this.text(l, src));
       if (modifier.getChild("On")) on = names;
       else ignoring = names;
-      if (modifier.getChild("GroupLeft") || modifier.getChild("GroupRight")) throw new Error("rule-eval: group_left/right is not supported");
+      if (modifier.getChild("GroupRight")) throw new Error("rule-eval: group_right is not supported");
+      const left = modifier.getChild("GroupLeft");
+      if (left) {
+        // group_left(<labels>) copies labels from the one side; only the bare form is supported.
+        const after = left.nextSibling;
+        if (after && after.name === "GroupingLabels" && after !== grouping) throw new Error("rule-eval: group_left with labels is not supported");
+        groupLeft = true;
+      }
     }
     const lhs = this.node(lhsNode, src, t);
     const rhs = this.node(rhsNode, src, t);
@@ -377,6 +434,14 @@ export class RuleEvaluator {
       if (bySig.has(s)) throw new Error("rule-eval: many-to-many matching is not supported");
       bySig.set(s, e);
     }
+    if (!groupLeft) {
+      const seen = new Set<string>();
+      for (const e of l.elements) {
+        const s = signature(e.labels);
+        if (seen.has(s)) throw new Error("rule-eval: many-to-one matching needs group_left");
+        seen.add(s);
+      }
+    }
     const elements: VectorElement[] = [];
     for (const e of l.elements) {
       const other = bySig.get(signature(e.labels));

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/skills/chant-prometheus.md

@@ -100,3 +100,25 @@ sloMetrics(checkout).errorRatio["1h"]; // "slo:sli_error:ratio_rate1h"
 - Write the objective as a fraction strictly between 0 and 1, and put `{{window}}` where each SLI expression's range goes (PROM003).
 - Alerts carry `severity` `page` or `ticket`; route both (PROM202).
 - Read series names from `sloMetrics()` in dashboards instead of repeating them.
+
+## GenAI rules
+
+`GenAiRules` builds rules for the otel lexicon's GenAI collector preset from the same `genAiMetrics(options)` the collector was built with: request rate, error ratio (also by `error.type`) and p50/p95/p99 latency per provider, model and operation, token rates, spend per second from a price table the project declares, and per-tool call rate, error ratio and p95 latency. Alerts are off unless `alerts` names them.
+
+```ts
+import { genAiMetrics } from "@intentius/chant-lexicon-otel";
+import { GenAiRules, genAiRuleMetrics } from "@intentius/chant-lexicon-prometheus";
+
+export const genai = GenAiRules({
+  genAi: genAiMetrics({ clientMetrics: "derive" }),
+  prices: [{ provider: "anthropic", model: "claude-x", inputPerMTok: 3, outputPerMTok: 15, currency: "USD", source: "https://example.com/pricing", asOf: "2026-09-29" }],
+  alerts: { errorRatio: true, latency: { thresholdSeconds: 20 }, budgets: [{ amount: 50, currency: "USD", per: "day" }] },
+});
+
+genAiRuleMetrics(genai).cost; // "gen_ai:cost:rate5m"
+```
+
+- Pass the collector's own options to `genAiMetrics()`; never write a metric name by hand.
+- Ship no prices in a lexicon or template. The project declares them, with `currency` and `source` on each.
+- A model missing from `prices` gets no cost series, so a sum of the cost series covers priced models only.
+- Read series names from `genAiRuleMetrics()` in dashboards.

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/typecheck.test.ts

@@ -0,0 +1,88 @@
+/**
+ * Type-level guarantees of the hand-written declarations. Each
+ * `@ts-expect-error` line must fail to compile: `tsconfig.typecheck.json`
+ * (scripts/typecheck.ts in CI) fails on an unused one, so a type that starts
+ * accepting what it used to reject breaks the build. The invalid declarations
+ * sit in functions that are never called, so nothing here throws at runtime.
+ */
+import { describe, expectTypeOf, test } from "vitest";
+import {
+  Receiver,
+  Route,
+  RuleGroup,
+  Slo,
+  TimeInterval,
+  sloMetrics,
+  type ReceiverEntity,
+  type Rule,
+  type RuleGroupEntity,
+  type RuleGroupProps,
+  type SloMetrics,
+  type SloProps,
+} from "./index";
+
+describe("rule groups", () => {
+  test("a group needs a name and rules, and every rule an expr", () => {
+    expectTypeOf(RuleGroup).constructorParameters.toEqualTypeOf<[RuleGroupProps]>();
+    expectTypeOf<RuleGroupProps["rules"]>().toEqualTypeOf<Rule[]>();
+    expectTypeOf(new RuleGroup({ name: "api", rules: [] })).toEqualTypeOf<RuleGroupEntity>();
+
+    const rejected = () => [
+      // @ts-expect-error a group without a name
+      new RuleGroup({ rules: [] }),
+      // @ts-expect-error a group without rules
+      new RuleGroup({ name: "api" }),
+      // @ts-expect-error a recording rule without its expression
+      new RuleGroup({ name: "api", rules: [{ record: "job:up:sum" }] }),
+      // @ts-expect-error an alerting rule without its expression
+      new RuleGroup({ name: "api", rules: [{ alert: "Down", for: "5m" }] }),
+      // @ts-expect-error label values are strings, as Prometheus stores them
+      new RuleGroup({ name: "api", rules: [{ alert: "Down", expr: "up == 0", labels: { priority: 1 } }] }),
+      // @ts-expect-error `for` is a duration string, not a number of seconds
+      new RuleGroup({ name: "api", rules: [{ alert: "Down", expr: "up == 0", for: 300 }] }),
+    ];
+    void rejected;
+  });
+});
+
+describe("alertmanager", () => {
+  test("a route names a receiver, and its time intervals by TimeInterval, never the other way round", () => {
+    const oncall = new Receiver({ name: "oncall" });
+    const weekend = new TimeInterval({ name: "weekend", time_intervals: [{ weekdays: ["saturday", "sunday"] }] });
+    expectTypeOf(oncall).toEqualTypeOf<ReceiverEntity>();
+
+    // By entity or by name, for a receiver declared outside the build.
+    new Route({ receiver: oncall, mute_time_intervals: [weekend] });
+    new Route({ receiver: "oncall", mute_time_intervals: ["weekend"] });
+
+    const rejected = () => [
+      // @ts-expect-error a time interval is not a receiver
+      new Route({ receiver: weekend }),
+      // @ts-expect-error a receiver is not a time interval
+      new Route({ receiver: oncall, mute_time_intervals: [oncall] }),
+      // @ts-expect-error a receiver needs a name
+      new Receiver({ webhook_configs: [{ url: "http://hook:8080/" }] }),
+    ];
+    void rejected;
+  });
+});
+
+describe("Slo", () => {
+  test("an SLO needs a name, objective, window and an SLI over total events", () => {
+    const sli = { errors: "sum(rate(errors_total[{{window}}]))", total: "sum(rate(requests_total[{{window}}]))" };
+    const slo = Slo({ name: "checkout", objective: 0.999, window: "30d", sli });
+    expectTypeOf(slo.rules).toEqualTypeOf<RuleGroupEntity>();
+    expectTypeOf(sloMetrics(slo)).toEqualTypeOf<SloMetrics>();
+    expectTypeOf(Slo).parameter(0).toEqualTypeOf<SloProps>();
+
+    const rejected = () => [
+      // @ts-expect-error the objective is a fraction, not a string
+      Slo({ name: "checkout", objective: "99.9%", window: "30d", sli }),
+      // @ts-expect-error an SLO without a window
+      Slo({ name: "checkout", objective: 0.999, sli }),
+      // @ts-expect-error an SLI without total events has no ratio
+      Slo({ name: "checkout", objective: 0.999, window: "30d", sli: { errors: sli.errors } }),
+    ];
+    void rejected;
+  });
+});

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.
   }