@intentius/chant-lexicon-prometheus 0.124.31 → 0.124.33

package/dist/tools.js

@@ -0,0 +1,85 @@
+/**
+ * `promtool check rules`, `promtool check config` 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 { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { dirname, join } from "path";
+/** True when `bin` is on PATH (or is a path that runs). */
+export function hasTool(bin) {
+    const r = spawnSync(bin, ["--version"], { encoding: "utf-8" });
+    return !r.error && r.status === 0;
+}
+function runOnText(bin, args, filename, text) {
+    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, bin = process.env.PROMTOOL ?? "promtool") {
+    return runOnText(bin, (f) => ["check", "rules", f], "rules.yml", yaml);
+}
+/**
+ * Run `promtool check config` over `prometheus.yml` text. The config is written
+ * as `prometheus.yml` in a directory of its own, and `files` (path relative to
+ * that directory to contents) are written beside it: `check config` also reads
+ * the rule files, certificates and credentials files the config names, so a
+ * config that names any needs them here. `bin` defaults to `promtool` on PATH.
+ */
+export function promtoolCheckConfig(yaml, files = {}, bin = process.env.PROMTOOL ?? "promtool") {
+    if (!hasTool(bin))
+        return { ran: false, ok: false, output: "" };
+    const dir = mkdtempSync(join(tmpdir(), "chant-prometheus-"));
+    try {
+        writeFileSync(join(dir, "prometheus.yml"), yaml);
+        for (const [path, content] of Object.entries(files)) {
+            const target = join(dir, path);
+            mkdirSync(dirname(target), { recursive: true });
+            writeFileSync(target, content);
+        }
+        const r = spawnSync(bin, ["check", "config", "prometheus.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 `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, testYaml, bin = process.env.PROMTOOL ?? "promtool") {
+    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, bin = process.env.AMTOOL ?? "amtool") {
+    return runOnText(bin, (f) => ["check-config", f], "alertmanager.yml", yaml);
+}

package/dist/validate-cli.js

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

package/dist/validate-config.js

@@ -0,0 +1,556 @@
+/**
+ * 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 { durationMs, formatDuration, isValidDuration } from "./duration.js";
+import { matcherMatches, parseMatchers } from "./matchers.js";
+import { isAlertingRuleConfig, isRecordingRuleConfig, } from "./model.js";
+import { checkPromql } from "./promql.js";
+import { hasCondition, histogramProblems, isMultiWindow, keepsLabel, nonCounterRates, parsePromql, readsOnlyOverTime, regexProblems, resultLabels, selectors, } from "./promql-analysis.js";
+import { validateGlobalSettings, validateReceiverIntegrations } from "./validate-integrations.js";
+import { validateGlobalSecurity, validateReceiverSecurity } from "./validate-security.js";
+function str(v) {
+    return typeof v === "string" ? v : String(v);
+}
+// ── Rule files ──────────────────────────────────────────────────────
+function ruleLabel(group, index, rule) {
+    const r = rule;
+    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, rule) {
+    return { ...(group.labels ?? {}), ...(rule.labels ?? {}) };
+}
+/** The `$labels.x`, `.Labels.x` and `index $labels "x"` references in a template. */
+function templateLabels(template) {
+    const out = new Set();
+    for (const re of [/\$labels\.([A-Za-z_][A-Za-z0-9_]*)/g, /\.Labels\.([A-Za-z_][A-Za-z0-9_]*)/g, /index\s+\$labels\s+"([^"]+)"/g]) {
+        for (const m of template.matchAll(re))
+            out.add(m[1]);
+    }
+    return [...out];
+}
+/** `level:metric:operations`: three or more non-empty parts separated by colons. */
+const RECORD_NAME = /^[a-zA-Z_][a-zA-Z0-9_]*(?::[a-zA-Z0-9_]+){2,}$/;
+/** PROM215, PROM216 and PROM218: what any rule's expression can get wrong. */
+function exprIssues(expr, subject) {
+    const issues = [];
+    for (const { fn, name } of nonCounterRates(expr)) {
+        issues.push({
+            code: "PROM215",
+            severity: "warning",
+            subject,
+            message: `rule ${subject} takes ${fn}() of ${name}, whose name does not end in _total, _count, _sum or _bucket; ${fn}() reads only counters, so use delta() or deriv() for a gauge`,
+        });
+    }
+    for (const { call, problem } of histogramProblems(expr)) {
+        issues.push({
+            code: "PROM216",
+            severity: "warning",
+            subject,
+            message: problem === "no-bucket"
+                ? `rule ${subject} ${call} reads a series without _bucket in its name; a classic histogram's quantile needs its _bucket series`
+                : `rule ${subject} ${call} aggregates away the le label; keep le in by (...), or out of without (...)`,
+        });
+    }
+    for (const { matcher, problem } of regexProblems(expr)) {
+        issues.push({
+            code: "PROM218",
+            severity: "warning",
+            subject,
+            message: problem === "literal"
+                ? `rule ${subject} matcher ${matcher} has no regex metacharacters; use = or != instead`
+                : `rule ${subject} matcher ${matcher} is anchored; Prometheus anchors every regex, so drop the ^ and $`,
+        });
+    }
+    return issues;
+}
+/** PROM211, PROM213, PROM214 and PROM219: alerting rules. */
+function alertIssues(group, rule, subject) {
+    const issues = [];
+    const expr = typeof rule.expr === "string" ? rule.expr : "";
+    // An expression that reads no series (`vector(1)`) is a deliberate always-firing
+    // alert, a dead man's switch; PROM211 and PROM213 leave it alone.
+    const heartbeat = parsePromql(expr) !== undefined && selectors(expr).length === 0;
+    // PROM211: no for, or for: 0s. An expression that already spans a window
+    // (every selector read through *_over_time, or the multi-window `and` of two
+    // conditions, where the short window does what for would) is left alone. A
+    // for that is not a duration is PROM103's.
+    const forMs = rule.for === undefined ? 0 : durationMs(str(rule.for));
+    if (forMs === 0 && !heartbeat && !readsOnlyOverTime(expr) && !isMultiWindow(expr)) {
+        issues.push({
+            code: "PROM211",
+            severity: "warning",
+            subject,
+            message: `alert ${subject} has ${rule.for === undefined ? "no for" : `for: ${str(rule.for)}`}, so one evaluation that matches fires it; set for to how long the condition must hold`,
+        });
+    }
+    // PROM213: no condition
+    if (!heartbeat && hasCondition(expr) === false) {
+        issues.push({
+            code: "PROM213",
+            severity: "warning",
+            subject,
+            message: `alert ${subject} expression has no comparison, so it fires for every series it returns; add a condition such as > 0`,
+        });
+    }
+    // PROM214: a template reads a label the expression aggregates away. A label
+    // the rule or its group sets is left alone.
+    const scope = resultLabels(expr);
+    if (scope) {
+        const fixed = alertLabels(group, rule);
+        const reported = new Set();
+        for (const [key, value] of [...Object.entries(rule.annotations ?? {}), ...Object.entries(rule.labels ?? {})]) {
+            for (const label of templateLabels(str(value))) {
+                if (keepsLabel(scope, label) || label in fixed || reported.has(label))
+                    continue;
+                reported.add(label);
+                issues.push({
+                    code: "PROM214",
+                    severity: "warning",
+                    subject,
+                    message: `alert ${subject} ${key} reads $labels.${label}, which the expression's by or without drops, so it renders empty`,
+                });
+            }
+        }
+    }
+    // PROM219: alertname set by hand
+    for (const [where, labels] of [
+        ["labels", rule.labels],
+        ["group labels", group.labels],
+    ]) {
+        if (labels && Object.prototype.hasOwnProperty.call(labels, "alertname")) {
+            issues.push({
+                code: "PROM219",
+                severity: "warning",
+                subject,
+                message: `alert ${subject} ${where} set alertname; Prometheus sets alertname to the rule's name and overwrites it`,
+            });
+        }
+    }
+    return issues;
+}
+/** Check a rule file (PROM101-PROM107, PROM211 and PROM213-PROM219). PROM212 is opt-in; see {@link validateRunbookUrls}. */
+export function validateRuleFile(file) {
+    const issues = [];
+    const groups = Array.isArray(file?.groups) ? file.groups : [];
+    const groupNames = new Map();
+    const ruleKeys = new Map();
+    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"]) {
+            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;
+            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.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);
+                const key = JSON.stringify([recording ? "record" : "alert", recording ? rule.record : rule.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);
+                // 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.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`,
+                    });
+                }
+                issues.push(...alertIssues(group, rule, subject));
+            }
+            // PROM217: recording rule name
+            if (recording && !alerting && rule.record.trim() !== "" && !RECORD_NAME.test(rule.record)) {
+                issues.push({
+                    code: "PROM217",
+                    severity: "warning",
+                    subject,
+                    message: `recording rule ${subject} is not named level:metric:operations (e.g. job:http_requests:rate5m)`,
+                });
+            }
+            if (checked.ok)
+                issues.push(...exprIssues(expr, subject));
+        });
+    }
+    return issues;
+}
+/**
+ * PROM212: alerts without a `runbook_url` annotation. Not part of
+ * {@link validateRuleFile}, because the check is opt-in: the lint preset
+ * `all`, or a `lint.rules` entry for PROM212, turns it on.
+ */
+export function validateRunbookUrls(file) {
+    const issues = [];
+    for (const group of Array.isArray(file?.groups) ? file.groups : []) {
+        (Array.isArray(group?.rules) ? group.rules : []).forEach((rule, i) => {
+            if (!isAlertingRuleConfig(rule) || rule.annotations?.runbook_url)
+                return;
+            const subject = ruleLabel(group, i, rule);
+            issues.push({ code: "PROM212", severity: "warning", subject, message: `alert ${subject} has no runbook_url annotation` });
+        });
+    }
+    return issues;
+}
+/** Every severity value an alert in these rule files carries, with the alerts carrying it. */
+export function alertSeverities(files) {
+    const out = new Map();
+    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;
+}
+function visitRoutes(root) {
+    const out = [];
+    const walk = (route, path, depth) => {
+        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"];
+/** Alertmanager's defaults for a root route that sets neither (config/config.go). */
+const DEFAULT_GROUP_INTERVAL_MS = 5 * 60000;
+const DEFAULT_REPEAT_INTERVAL_MS = 4 * 3600000;
+/**
+ * PROM223: routes whose repeat_interval, as set or inherited, is shorter
+ * than their group_interval. Alertmanager only resends when a group is
+ * flushed, every group_interval, so the shorter repeat_interval never takes
+ * effect. Reported on the route that sets one of the two.
+ */
+function repeatIntervalIssues(root) {
+    const issues = [];
+    const walk = (route, path, groupMs, repeatMs) => {
+        const ownGroup = route.group_interval !== undefined ? durationMs(str(route.group_interval)) : groupMs;
+        const ownRepeat = route.repeat_interval !== undefined ? durationMs(str(route.repeat_interval)) : repeatMs;
+        if (ownGroup === undefined || ownRepeat === undefined)
+            return; // PROM208
+        if ((route.group_interval !== undefined || route.repeat_interval !== undefined) && ownRepeat < ownGroup) {
+            issues.push({
+                code: "PROM223",
+                severity: "warning",
+                subject: path,
+                message: `${path} repeat_interval (${formatDuration(ownRepeat)}) is shorter than its group_interval (${formatDuration(ownGroup)}); notifications repeat no faster than group_interval`,
+            });
+        }
+        (Array.isArray(route.routes) ? route.routes : []).forEach((child, i) => walk(child, `${path}.routes[${i}]`, ownGroup, ownRepeat));
+    };
+    if (root && typeof root === "object")
+        walk(root, "route", DEFAULT_GROUP_INTERVAL_MS, DEFAULT_REPEAT_INTERVAL_MS);
+    return issues;
+}
+function parsedList(entries) {
+    const out = [];
+    for (const m of Array.isArray(entries) ? entries : []) {
+        const parsed = parseMatchers(str(m));
+        if (!parsed.ok)
+            return undefined; // PROM206
+        out.push(...parsed.matchers);
+    }
+    return out;
+}
+/** A regex's alternatives when every one is a plain string, e.g. `a|b` gives `["a", "b"]`. */
+function literalAlternatives(regex) {
+    const parts = regex.split("|");
+    return parts.every((p) => !/[.+*?()[\]{}\\^$]/.test(p)) ? parts : undefined;
+}
+/**
+ * Whether some label set matches every matcher. A label whose matchers
+ * name values (`=`, or a regex of plain alternatives) is tried with those
+ * values; one with only negative or open-ended matchers is taken to have a
+ * value that passes.
+ */
+function satisfiable(matchers) {
+    const byLabel = new Map();
+    for (const m of matchers)
+        byLabel.set(m.name, [...(byLabel.get(m.name) ?? []), m]);
+    for (const [name, ms] of byLabel) {
+        const candidates = new Set();
+        let bounded = false;
+        for (const m of ms) {
+            if (m.op === "=") {
+                candidates.add(m.value);
+                bounded = true;
+            }
+            else if (m.op === "=~") {
+                const alts = literalAlternatives(m.value);
+                if (alts) {
+                    alts.forEach((a) => candidates.add(a));
+                    bounded = true;
+                }
+            }
+        }
+        if (!bounded)
+            continue;
+        if (![...candidates].some((v) => ms.every((m) => matcherMatches(m, { [name]: v }))))
+            return false;
+    }
+    return true;
+}
+/** Check an `alertmanager.yml` on its own (PROM201, PROM203-PROM210, PROM220-PROM224). */
+export function validateAlertmanagerConfig(config) {
+    const issues = [];
+    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();
+    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();
+    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();
+    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"]) {
+            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"]) {
+            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}` });
+                }
+            }
+        }
+    });
+    // PROM223: repeat_interval under group_interval
+    issues.push(...repeatIntervalIssues(root));
+    // PROM224: an inhibit rule an alert can be both source and target of, with no equal
+    (Array.isArray(config?.inhibit_rules) ? config.inhibit_rules : []).forEach((rule, i) => {
+        if (Array.isArray(rule?.equal) && rule.equal.length > 0)
+            return;
+        const source = parsedList(rule?.source_matchers);
+        const target = parsedList(rule?.target_matchers);
+        if (!source || !target || !satisfiable([...source, ...target]))
+            return;
+        issues.push({
+            code: "PROM224",
+            severity: "warning",
+            subject: `inhibit_rules[${i}]`,
+            message: `inhibit_rules[${i}]: one alert can match both source_matchers and target_matchers, and there is no equal, so any such alert firing mutes every other; list the labels the two must share under equal`,
+        });
+    });
+    // PROM208, PROM210: global settings; PROM220: global TLS
+    issues.push(...validateGlobalSettings(global));
+    issues.push(...validateGlobalSecurity(global));
+    // 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` });
+        }
+        issues.push(...validateReceiverIntegrations(r, global));
+        issues.push(...validateReceiverSecurity(r, global));
+        // A receiver with no integrations at all is valid: it is how Alertmanager drops alerts.
+    }
+    return issues;
+}
+function severityMatchers(route) {
+    const out = [];
+    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, config) {
+    const severities = alertSeverities(ruleFiles);
+    if (severities.size === 0 || !config?.route)
+        return [];
+    const paths = [];
+    const walk = (route, inherited, depth) => {
+        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 = [];
+    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;
+}