@intentius/chant-lexicon-prometheus 0.96.0

package/src/tools.test.ts

@@ -0,0 +1,119 @@
+/**
+ * promtool and amtool, over output the lexicon builds. Each test runs the
+ * real binary when it is on PATH (or named by $PROMTOOL / $AMTOOL) and skips
+ * otherwise; the structural checks in post-synth.test.ts always run.
+ */
+import { describe, expect, test } from "vitest";
+import {
+  AlertmanagerSettings,
+  InhibitRule,
+  Receiver,
+  Route,
+  RuleGroup,
+  TimeInterval,
+  alertmanagerYaml,
+  amtoolCheckConfig,
+  hasTool,
+  promtoolCheckRules,
+  ruleFileYaml,
+} from "./index";
+
+const PROMTOOL = process.env.PROMTOOL ?? "promtool";
+const AMTOOL = process.env.AMTOOL ?? "amtool";
+const hasPromtool = hasTool(PROMTOOL);
+const hasAmtool = hasTool(AMTOOL);
+
+function groups() {
+  return [
+    new RuleGroup({
+      name: "api",
+      interval: "30s",
+      query_offset: "1m",
+      labels: { team: "api" },
+      rules: [
+        {
+          record: "job:http_errors:ratio5m",
+          expr: 'sum by (job) (rate(http_requests_total{code=~"5.."}[5m]))\n  / sum by (job) (rate(http_requests_total[5m]))',
+        },
+        {
+          alert: "ApiErrors",
+          expr: "job:http_errors:ratio5m > 0.05",
+          for: "10m",
+          keep_firing_for: "5m",
+          labels: { severity: "page" },
+          annotations: { summary: "{{ $labels.job }} 5xx ratio is {{ $value | humanizePercentage }}" },
+        },
+        { alert: "ApiErrors", expr: "job:http_errors:ratio5m > 0.01", for: "1h", labels: { severity: "ticket" }, annotations: { summary: "x: y" } },
+      ],
+    }),
+    new RuleGroup({ name: "limits", limit: 10, rules: [{ alert: "TooMany", expr: "count(up) > 100", labels: { severity: "ticket" } }] }),
+  ];
+}
+
+function alertmanager() {
+  const oncall = new Receiver({
+    name: "oncall",
+    pagerduty_configs: [{ routing_key_file: "/etc/alertmanager/pd", severity: "critical" }],
+    slack_configs: [{ api_url_file: "/etc/alertmanager/slack", channel: "#alerts", send_resolved: true }],
+  });
+  const mail = new Receiver({
+    name: "mail",
+    email_configs: [{ to: "team@example.com", auth_username: "am", auth_password_file: "/etc/alertmanager/smtp" }],
+  });
+  const sink = new Receiver({ name: "default", webhook_configs: [{ url: "http://sink:8080/", max_alerts: 10, timeout: "10s" }] });
+  const weekend = new TimeInterval({
+    name: "weekend",
+    time_intervals: [{ weekdays: ["saturday", "sunday"] }, { times: [{ start_time: "18:00", end_time: "24:00" }], location: "Europe/Berlin" }],
+  });
+  return [
+    new AlertmanagerSettings({ global: { resolve_timeout: "5m", smtp_smarthost: "smtp.example.com:587", smtp_from: "am@example.com" } }),
+    new Route({
+      receiver: sink,
+      group_by: ["alertname", "job"],
+      group_wait: "30s",
+      group_interval: "5m",
+      repeat_interval: "4h",
+      routes: [
+        { matchers: ['severity="page"'], receiver: oncall, continue: true },
+        { matchers: ['severity=~"ticket|info"'], receiver: mail, mute_time_intervals: [weekend] },
+      ],
+    }),
+    new InhibitRule({ source_matchers: ['severity="page"'], target_matchers: ['severity="ticket"'], equal: ["alertname"] }),
+  ];
+}
+
+describe("promtool check rules", () => {
+  test.skipIf(!hasPromtool)("accepts the rule file the lexicon builds", () => {
+    const r = promtoolCheckRules(ruleFileYaml(groups()), PROMTOOL);
+    expect(r.ran).toBe(true);
+    expect(r.output).toContain("SUCCESS");
+    expect(r.ok).toBe(true);
+  });
+
+  test.skipIf(!hasPromtool)("rejects what PROM101 flags, so the two agree", () => {
+    const [g] = groups();
+    const r = promtoolCheckRules(ruleFileYaml([g, new RuleGroup({ name: "api", rules: [] })]), PROMTOOL);
+    expect(r.ok).toBe(false);
+  });
+
+  test("reports ran: false when the binary is missing", () => {
+    expect(promtoolCheckRules("groups: []\n", "/nonexistent/promtool")).toEqual({ ran: false, ok: false, output: "" });
+  });
+});
+
+describe("amtool check-config", () => {
+  test.skipIf(!hasAmtool)("accepts the alertmanager.yml the lexicon builds", () => {
+    const r = amtoolCheckConfig(alertmanagerYaml(alertmanager()), AMTOOL);
+    expect(r.ran).toBe(true);
+    expect(r.ok, r.output).toBe(true);
+  });
+
+  test.skipIf(!hasAmtool)("rejects what PROM201 flags, so the two agree", () => {
+    const r = amtoolCheckConfig(alertmanagerYaml([new Route({ receiver: "nobody" })]), AMTOOL);
+    expect(r.ok).toBe(false);
+  });
+
+  test("reports ran: false when the binary is missing", () => {
+    expect(amtoolCheckConfig("route: {}\n", "/nonexistent/amtool").ran).toBe(false);
+  });
+});

package/src/tools.ts

@@ -0,0 +1,70 @@
+/**
+ * `promtool check rules` and `amtool check-config`, when they are installed.
+ *
+ * The lexicon's own checks cover structure, references and PromQL syntax.
+ * The upstream tools add what only Prometheus and Alertmanager know (PromQL
+ * types, template parsing in annotations, every receiver field). They are
+ * not bundled and not run by `chant build`, so a build gives the same answer
+ * everywhere; tests, e2e runs and CI jobs call these helpers, which report
+ * `ran: false` when the binary isn't on PATH instead of failing.
+ */
+
+import { spawnSync } from "child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+
+export interface ToolResult {
+  /** False when the binary isn't installed; `ok` and `output` are then meaningless. */
+  ran: boolean;
+  ok: boolean;
+  /** Combined stdout and stderr. */
+  output: string;
+}
+
+/** True when `bin` is on PATH (or is a path that runs). */
+export function hasTool(bin: string): boolean {
+  const r = spawnSync(bin, ["--version"], { encoding: "utf-8" });
+  return !r.error && r.status === 0;
+}
+
+function runOnText(bin: string, args: (file: string) => string[], filename: string, text: string): ToolResult {
+  if (!hasTool(bin)) return { ran: false, ok: false, output: "" };
+  const dir = mkdtempSync(join(tmpdir(), "chant-prometheus-"));
+  try {
+    const file = join(dir, filename);
+    writeFileSync(file, text);
+    const r = spawnSync(bin, args(file), { encoding: "utf-8" });
+    return { ran: true, ok: r.status === 0, output: `${r.stdout ?? ""}${r.stderr ?? ""}` };
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/** Run `promtool check rules` over rule file YAML. `bin` defaults to `promtool` on PATH. */
+export function promtoolCheckRules(yaml: string, bin = process.env.PROMTOOL ?? "promtool"): ToolResult {
+  return runOnText(bin, (f) => ["check", "rules", f], "rules.yml", yaml);
+}
+
+/**
+ * Run `promtool test rules` over rule file YAML and a unit-test file for it.
+ * The test file's `rule_files:` should name `rules.yml`, which is where the
+ * rule file is written beside it. `bin` defaults to `promtool` on PATH.
+ */
+export function promtoolTestRules(rulesYaml: string, testYaml: string, bin = process.env.PROMTOOL ?? "promtool"): ToolResult {
+  if (!hasTool(bin)) return { ran: false, ok: false, output: "" };
+  const dir = mkdtempSync(join(tmpdir(), "chant-prometheus-"));
+  try {
+    writeFileSync(join(dir, "rules.yml"), rulesYaml);
+    writeFileSync(join(dir, "rules.test.yml"), testYaml);
+    const r = spawnSync(bin, ["test", "rules", "rules.test.yml"], { cwd: dir, encoding: "utf-8" });
+    return { ran: true, ok: r.status === 0, output: `${r.stdout ?? ""}${r.stderr ?? ""}` };
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/** Run `amtool check-config` over `alertmanager.yml` text. `bin` defaults to `amtool` on PATH. */
+export function amtoolCheckConfig(yaml: string, bin = process.env.AMTOOL ?? "amtool"): ToolResult {
+  return runOnText(bin, (f) => ["check-config", f], "alertmanager.yml", yaml);
+}

package/src/validate-cli.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env tsx
+import { printValidationResult } from "@intentius/chant/codegen/validate";
+import { validate } from "./validate";
+
+const result = await validate();
+printValidationResult(result);
+if (!result.success) process.exit(1);

package/src/validate-config.ts

@@ -0,0 +1,400 @@
+/**
+ * Rule file and Alertmanager config checks, as plain functions over the
+ * parsed files.
+ *
+ * The post-synth checks in `lint/post-synth/` are thin wrappers around these,
+ * so the same rules run anywhere the files exist: on a build's output, on a
+ * `PrometheusRule`'s groups, or on a file parsed by some other tool.
+ */
+
+import { isValidDuration } from "./duration";
+import { matcherMatches, parseMatchers, type Matcher } from "./matchers";
+import {
+  isAlertingRuleConfig,
+  isRecordingRuleConfig,
+  type AlertmanagerConfig,
+  type AlertingRuleConfig,
+  type LabelSet,
+  type RouteConfig,
+  type RuleFileConfig,
+  type RuleGroupConfig,
+} from "./model";
+import { checkPromql } from "./promql";
+
+export type PrometheusIssueCode =
+  | "PROM101"
+  | "PROM102"
+  | "PROM103"
+  | "PROM104"
+  | "PROM105"
+  | "PROM106"
+  | "PROM107"
+  | "PROM201"
+  | "PROM202"
+  | "PROM203"
+  | "PROM204"
+  | "PROM205"
+  | "PROM206"
+  | "PROM207"
+  | "PROM208"
+  | "PROM209";
+
+export interface PrometheusIssue {
+  code: PrometheusIssueCode;
+  severity: "error" | "warning";
+  message: string;
+  /** What the issue is about: a group, a rule (`group/rule`), a receiver or a route. */
+  subject?: string;
+}
+
+function str(v: unknown): string {
+  return typeof v === "string" ? v : String(v);
+}
+
+// ── Rule files ──────────────────────────────────────────────────────
+
+function ruleLabel(group: RuleGroupConfig, index: number, rule: unknown): string {
+  const r = rule as Record<string, unknown>;
+  const name = typeof r?.record === "string" ? r.record : typeof r?.alert === "string" ? r.alert : `rule ${index + 1}`;
+  return `${group.name}/${name}`;
+}
+
+/** The static labels an alert carries: the group's labels under its own. */
+function alertLabels(group: RuleGroupConfig, rule: AlertingRuleConfig): LabelSet {
+  return { ...(group.labels ?? {}), ...(rule.labels ?? {}) };
+}
+
+/** Check a rule file (PROM101-PROM107). */
+export function validateRuleFile(file: RuleFileConfig): PrometheusIssue[] {
+  const issues: PrometheusIssue[] = [];
+  const groups = Array.isArray(file?.groups) ? file.groups : [];
+  const groupNames = new Map<string, number>();
+  const ruleKeys = new Map<string, string>();
+
+  for (const group of groups) {
+    const gname = str(group?.name ?? "");
+    groupNames.set(gname, (groupNames.get(gname) ?? 0) + 1);
+    if (groupNames.get(gname) === 2) {
+      issues.push({
+        code: "PROM101",
+        severity: "error",
+        subject: gname,
+        message: `rule group "${gname}" is declared more than once; Prometheus requires group names to be unique within a rule file`,
+      });
+    }
+    if (gname.trim() === "") {
+      issues.push({ code: "PROM105", severity: "error", subject: gname, message: "a rule group has no name" });
+    }
+
+    for (const field of ["interval", "query_offset"] as const) {
+      const v = group?.[field];
+      if (v !== undefined && !isValidDuration(v)) {
+        issues.push({
+          code: "PROM103",
+          severity: "error",
+          subject: gname,
+          message: `group "${gname}" ${field} "${str(v)}" is not a Prometheus duration (e.g. 30s, 1m, 1h30m)`,
+        });
+      }
+    }
+
+    const rules = Array.isArray(group?.rules) ? group.rules : [];
+    rules.forEach((rule, i) => {
+      const subject = ruleLabel(group, i, rule);
+      const r = rule as unknown as Record<string, unknown>;
+      const recording = isRecordingRuleConfig(rule);
+      const alerting = isAlertingRuleConfig(rule);
+
+      // PROM105: shape
+      if (recording && alerting) {
+        issues.push({ code: "PROM105", severity: "error", subject, message: `rule ${subject} sets both record and alert; a rule is one or the other` });
+      } else if (!recording && !alerting) {
+        issues.push({ code: "PROM105", severity: "error", subject, message: `rule ${subject} sets neither record nor alert` });
+      } else if (recording) {
+        if (rule.record.trim() === "") issues.push({ code: "PROM105", severity: "error", subject, message: `a recording rule in group "${gname}" has an empty record name` });
+        for (const bad of ["for", "keep_firing_for", "annotations"]) {
+          if (r[bad] !== undefined) {
+            issues.push({ code: "PROM105", severity: "error", subject, message: `recording rule ${subject} sets ${bad}, which only alerting rules take` });
+          }
+        }
+      } else if (alerting && (rule as AlertingRuleConfig).alert.trim() === "") {
+        issues.push({ code: "PROM105", severity: "error", subject, message: `an alerting rule in group "${gname}" has an empty alert name` });
+      }
+
+      // PROM103: durations
+      for (const field of ["for", "keep_firing_for"]) {
+        const v = r[field];
+        if (v !== undefined && !isValidDuration(v)) {
+          issues.push({
+            code: "PROM103",
+            severity: "error",
+            subject,
+            message: `rule ${subject} ${field} "${str(v)}" is not a Prometheus duration (e.g. 5m, 1h)`,
+          });
+        }
+      }
+
+      // PROM104: PromQL
+      const expr = r.expr;
+      const checked = checkPromql(typeof expr === "string" ? expr : "");
+      if (!checked.ok) {
+        issues.push({ code: "PROM104", severity: "error", subject, message: `rule ${subject} expr: ${checked.message}` });
+      }
+
+      // PROM102: duplicates (same kind, name and labels anywhere in the file)
+      if (recording || alerting) {
+        const labels = recording ? { ...(group.labels ?? {}), ...(rule.labels ?? {}) } : alertLabels(group, rule as AlertingRuleConfig);
+        const key = JSON.stringify([recording ? "record" : "alert", recording ? rule.record : (rule as AlertingRuleConfig).alert, Object.entries(labels).sort()]);
+        const first = ruleKeys.get(key);
+        if (first !== undefined) {
+          issues.push({
+            code: "PROM102",
+            severity: "warning",
+            subject,
+            message: `rule ${subject} has the same name and labels as ${first}; the two produce the same series and overwrite each other`,
+          });
+        } else {
+          ruleKeys.set(key, subject);
+        }
+      }
+
+      if (alerting) {
+        const labels = alertLabels(group, rule as AlertingRuleConfig);
+        // PROM106: severity
+        if (!labels.severity) {
+          issues.push({
+            code: "PROM106",
+            severity: "warning",
+            subject,
+            message: `alert ${subject} has no severity label, so Alertmanager can only route it by name`,
+          });
+        }
+        // PROM107: summary/description
+        const ann = (rule as AlertingRuleConfig).annotations ?? {};
+        if (!ann.summary && !ann.description) {
+          issues.push({
+            code: "PROM107",
+            severity: "warning",
+            subject,
+            message: `alert ${subject} has no summary or description annotation; a notification carries only its labels`,
+          });
+        }
+      }
+    });
+  }
+  return issues;
+}
+
+/** Every severity value an alert in these rule files carries, with the alerts carrying it. */
+export function alertSeverities(files: RuleFileConfig[]): Map<string, string[]> {
+  const out = new Map<string, string[]>();
+  for (const file of files) {
+    for (const group of Array.isArray(file?.groups) ? file.groups : []) {
+      for (const rule of Array.isArray(group?.rules) ? group.rules : []) {
+        if (!isAlertingRuleConfig(rule)) continue;
+        const sev = alertLabels(group, rule).severity;
+        if (!sev) continue;
+        out.set(sev, [...(out.get(sev) ?? []), `${group.name}/${rule.alert}`]);
+      }
+    }
+  }
+  return out;
+}
+
+// ── Alertmanager ────────────────────────────────────────────────────
+
+interface RouteVisit {
+  route: RouteConfig;
+  path: string;
+  depth: number;
+}
+
+function visitRoutes(root: RouteConfig | undefined): RouteVisit[] {
+  const out: RouteVisit[] = [];
+  const walk = (route: RouteConfig, path: string, depth: number) => {
+    out.push({ route, path, depth });
+    (Array.isArray(route?.routes) ? route.routes : []).forEach((child, i) => walk(child, `${path}.routes[${i}]`, depth + 1));
+  };
+  if (root && typeof root === "object") walk(root, "route", 0);
+  return out;
+}
+
+const AM_DURATIONS = ["group_wait", "group_interval", "repeat_interval"] as const;
+
+/** Check an `alertmanager.yml` on its own (PROM201, PROM203-PROM209). */
+export function validateAlertmanagerConfig(config: AlertmanagerConfig): PrometheusIssue[] {
+  const issues: PrometheusIssue[] = [];
+  const receivers = Array.isArray(config?.receivers) ? config.receivers : [];
+  const intervals = Array.isArray(config?.time_intervals) ? config.time_intervals : [];
+  const global = config?.global ?? {};
+
+  // PROM203: duplicate names
+  const seenReceivers = new Set<string>();
+  for (const r of receivers) {
+    const name = str(r?.name ?? "");
+    if (seenReceivers.has(name)) {
+      issues.push({ code: "PROM203", severity: "error", subject: name, message: `receiver "${name}" is declared more than once; receiver names must be unique` });
+    }
+    seenReceivers.add(name);
+  }
+  const seenIntervals = new Set<string>();
+  for (const t of intervals) {
+    const name = str(t?.name ?? "");
+    if (seenIntervals.has(name)) {
+      issues.push({ code: "PROM203", severity: "error", subject: name, message: `time interval "${name}" is declared more than once; time interval names must be unique` });
+    }
+    seenIntervals.add(name);
+  }
+
+  // PROM205: root route shape
+  const root = config?.route;
+  if (!root || typeof root !== "object") {
+    issues.push({
+      code: "PROM205",
+      severity: "error",
+      subject: "route",
+      message: "alertmanager.yml has no root route; declare one Route with a receiver and nest the others under it",
+    });
+  } else {
+    if (!root.receiver) {
+      issues.push({ code: "PROM205", severity: "error", subject: "route", message: "the root route has no receiver; it is the default for every alert no child route takes" });
+    }
+    if (Array.isArray(root.matchers) && root.matchers.length > 0) {
+      issues.push({ code: "PROM205", severity: "error", subject: "route", message: "the root route has matchers; it must match every alert, so put matchers on child routes" });
+    }
+  }
+
+  const usedReceivers = new Set<string>();
+  for (const { route, path } of visitRoutes(root)) {
+    // PROM201: receiver exists
+    if (route.receiver !== undefined) {
+      const name = str(route.receiver);
+      usedReceivers.add(name);
+      if (!seenReceivers.has(name)) {
+        issues.push({ code: "PROM201", severity: "error", subject: path, message: `${path} sends to receiver "${name}", which is not declared` });
+      }
+    }
+    // PROM204: time intervals exist
+    for (const field of ["mute_time_intervals", "active_time_intervals"] as const) {
+      for (const t of route[field] ?? []) {
+        if (!seenIntervals.has(str(t))) {
+          issues.push({ code: "PROM204", severity: "error", subject: path, message: `${path} ${field} names time interval "${str(t)}", which is not declared` });
+        }
+      }
+    }
+    // PROM206: matchers parse
+    for (const m of route.matchers ?? []) {
+      const parsed = parseMatchers(str(m));
+      if (!parsed.ok) issues.push({ code: "PROM206", severity: "error", subject: path, message: `${path} matcher ${parsed.error}` });
+    }
+    // PROM208: durations
+    for (const field of AM_DURATIONS) {
+      const v = route[field];
+      if (v !== undefined && !isValidDuration(v)) {
+        issues.push({ code: "PROM208", severity: "error", subject: path, message: `${path} ${field} "${str(v)}" is not a duration (e.g. 30s, 5m, 4h)` });
+      }
+    }
+  }
+
+  (Array.isArray(config?.inhibit_rules) ? config.inhibit_rules : []).forEach((rule, i) => {
+    for (const field of ["source_matchers", "target_matchers"] as const) {
+      for (const m of rule?.[field] ?? []) {
+        const parsed = parseMatchers(str(m));
+        if (!parsed.ok) {
+          issues.push({ code: "PROM206", severity: "error", subject: `inhibit_rules[${i}]`, message: `inhibit_rules[${i}].${field} matcher ${parsed.error}` });
+        }
+      }
+    }
+  });
+
+  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` });
+  }
+
+  // PROM207: unused receivers; PROM209: incomplete integrations
+  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` });
+      }
+    }
+    // A receiver with no integrations at all is valid: it is how Alertmanager drops alerts.
+  }
+
+  return issues;
+}
+
+function severityMatchers(route: RouteConfig): Matcher[] | undefined {
+  const out: Matcher[] = [];
+  for (const m of route.matchers ?? []) {
+    const parsed = parseMatchers(str(m));
+    if (!parsed.ok) return undefined;
+    out.push(...parsed.matchers.filter((x) => x.name === "severity"));
+  }
+  return out;
+}
+
+/**
+ * PROM202: every severity an alert carries is taken by some route below the
+ * root that matches on `severity`. An alert whose severity no route names
+ * falls through to the root route's default receiver.
+ *
+ * Only matchers on `severity` are read, since other labels (team, service)
+ * come from the series and are not known at build time. A route counts when
+ * it, or a route above it, matches on `severity`, and every severity matcher
+ * on its path accepts the value.
+ */
+export function validateSeverityRouting(ruleFiles: RuleFileConfig[], config: AlertmanagerConfig): PrometheusIssue[] {
+  const severities = alertSeverities(ruleFiles);
+  if (severities.size === 0 || !config?.route) return [];
+
+  const paths: Matcher[][] = [];
+  const walk = (route: RouteConfig, inherited: Matcher[], depth: number) => {
+    const own = severityMatchers(route);
+    if (own === undefined) return; // PROM206 reports the unparseable matcher
+    const path = [...inherited, ...own];
+    if (depth > 0 && path.length > 0) paths.push(path);
+    for (const child of Array.isArray(route.routes) ? route.routes : []) walk(child, path, depth + 1);
+  };
+  walk(config.route, [], 0);
+
+  const issues: PrometheusIssue[] = [];
+  for (const [severity, alerts] of severities) {
+    const labels = { severity };
+    const routed = paths.some((path) => path.every((m) => matcherMatches(m, labels)));
+    if (!routed) {
+      const shown = alerts.slice(0, 3).join(", ") + (alerts.length > 3 ? `, and ${alerts.length - 3} more` : "");
+      issues.push({
+        code: "PROM202",
+        severity: "warning",
+        subject: severity,
+        message: `no route matches severity="${severity}" (${shown}); those alerts fall through to the root route's default receiver`,
+      });
+    }
+  }
+  return issues;
+}

package/src/validate.ts

@@ -0,0 +1,66 @@
+/**
+ * Validate the prometheus lexicon's own artifacts: every class is in the
+ * registry, every entity constructs and serializes, and a sample rule file
+ * and Alertmanager config pass the lexicon's own checks.
+ */
+
+import type { ValidateCheck, ValidateResult } from "@intentius/chant/codegen/validate";
+import { CATALOG, lexiconRegistry } from "./catalog";
+import { RuleGroup } from "./rules";
+import { AlertmanagerSettings, InhibitRule, Receiver, Route, TimeInterval } from "./alertmanager";
+import { buildAlertmanagerConfig, buildRuleFile } from "./build";
+import { validateAlertmanagerConfig, validateRuleFile } from "./validate-config";
+
+export type { ValidateCheck, ValidateResult } from "@intentius/chant/codegen/validate";
+
+/** Every entity class the package must keep exporting. */
+export const REQUIRED_NAMES = ["RuleGroup", "Route", "Receiver", "InhibitRule", "TimeInterval", "AlertmanagerSettings"];
+
+export async function validate(): Promise<ValidateResult> {
+  const checks: ValidateCheck[] = [];
+  const registry = lexiconRegistry();
+
+  const missing = REQUIRED_NAMES.filter((n) => !(n in registry));
+  checks.push(
+    missing.length === 0
+      ? { name: "required-names", ok: true }
+      : { name: "required-names", ok: false, error: `Missing required names: ${missing.join(", ")}` },
+  );
+
+  checks.push(
+    CATALOG.length === Object.keys(registry).length
+      ? { name: "catalog-matches-registry", ok: true }
+      : { name: "catalog-matches-registry", ok: false, error: "catalog and registry disagree" },
+  );
+
+  const group = new RuleGroup({
+    name: "sample",
+    interval: "30s",
+    rules: [
+      { record: "job:up:sum", expr: "sum by (job) (up)" },
+      { alert: "TargetDown", expr: "up == 0", for: "5m", labels: { severity: "page" }, annotations: { summary: "a target is down" } },
+    ],
+  });
+  const ruleIssues = validateRuleFile(buildRuleFile([group]).config);
+  checks.push(
+    ruleIssues.length === 0
+      ? { name: "rule-file-roundtrip", ok: true }
+      : { name: "rule-file-roundtrip", ok: false, error: ruleIssues.map((i) => i.message).join("; ") },
+  );
+
+  const hook = new Receiver({ name: "hook", webhook_configs: [{ url: "http://hook:8080/" }] });
+  const quiet = new TimeInterval({ name: "weekend", time_intervals: [{ weekdays: ["saturday", "sunday"] }] });
+  const entities = [
+    new AlertmanagerSettings({ global: { resolve_timeout: "5m" } }),
+    new Route({ receiver: hook, routes: [{ matchers: ['severity="page"'], receiver: hook, mute_time_intervals: [quiet] }] }),
+    new InhibitRule({ source_matchers: ['severity="page"'], target_matchers: ['severity="ticket"'], equal: ["alertname"] }),
+  ];
+  const amIssues = validateAlertmanagerConfig(buildAlertmanagerConfig(entities).config);
+  checks.push(
+    amIssues.length === 0
+      ? { name: "alertmanager-roundtrip", ok: true }
+      : { name: "alertmanager-roundtrip", ok: false, error: amIssues.map((i) => i.message).join("; ") },
+  );
+
+  return { success: checks.every((c) => c.ok), checks };
+}