@intentius/chant-lexicon-prometheus 0.96.0

package/src/init-templates.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, test } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { build } from "@intentius/chant/build";
+import { lintCommand } from "@intentius/chant/cli/commands/lint";
+import { initTemplates } from "./init-templates";
+import { prometheusSerializer } from "./serializer";
+import { postSynthChecks } from "./lint/post-synth";
+import { runPostSynthChecks } from "@intentius/chant/lint/post-synth";
+
+describe("init templates", () => {
+  test.each([undefined, "rules", "slo-style"])("%s builds, lints clean and passes every check", async (name) => {
+    const dir = mkdtempSync(join(import.meta.dirname, "..", ".init-template-"));
+    try {
+      mkdirSync(join(dir, "src"));
+      for (const [file, text] of Object.entries(initTemplates(name).src)) writeFileSync(join(dir, "src", file), text);
+      const result = await build(join(dir, "src"), [prometheusSerializer]);
+      expect(result.errors).toEqual([]);
+      expect(result.outputs.get("prometheus")).toBeTruthy();
+      const diags = runPostSynthChecks(postSynthChecks, result);
+      expect(diags).toEqual([]);
+      const lint = await lintCommand({ path: join(dir, "src"), format: "stylish", fix: false });
+      expect(lint.errorCount + lint.warningCount, lint.output).toBe(0);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/src/init-templates.ts

@@ -0,0 +1,76 @@
+/**
+ * `chant init --lexicon prometheus` scaffolds.
+ *
+ * - default: one rule group and the Alertmanager routing for it, in one build
+ *   root so PROM202 checks every severity is routed.
+ * - `rules`: rule groups only, for a setup whose Alertmanager config lives
+ *   elsewhere.
+ * - `slo-style`: a recording rule per window and alerts on two severities,
+ *   the shape SLO burn-rate rules take.
+ */
+import type { InitTemplateSet } from "@intentius/chant/lexicon";
+
+const RULES = `import { RuleGroup, type Rule } from "@intentius/chant-lexicon-prometheus";
+
+const rules: Rule[] = [
+  {
+    record: "job:http_errors:ratio5m",
+    expr: 'sum by (job) (rate(http_requests_total{code=~"5.."}[5m])) / sum by (job) (rate(http_requests_total[5m]))',
+  },
+  {
+    alert: "HttpErrorRatioHigh",
+    expr: "job:http_errors:ratio5m > 0.05",
+    for: "10m",
+    labels: { severity: "page" },
+    annotations: { summary: "{{ $labels.job }} is failing over 5% of requests" },
+  },
+];
+
+const api = new RuleGroup({ name: "api", interval: "30s", rules });
+
+export { api };
+`;
+
+const ALERTMANAGER = `import { Receiver, Route, type RouteProps, type WebhookConfig } from "@intentius/chant-lexicon-prometheus";
+
+const hook: WebhookConfig[] = [{ url: "http://alert-sink:8080/" }];
+const oncall = new Receiver({ name: "oncall", webhook_configs: hook });
+const fallback = new Receiver({ name: "default" });
+
+const children: RouteProps[] = [{ matchers: ['severity="page"'], receiver: oncall }];
+const byAlert = ["alertname", "job"];
+const root = new Route({ receiver: fallback, group_by: byAlert, routes: children });
+
+export { oncall, fallback, root };
+`;
+
+const SLO_STYLE = `import { RuleGroup, type Rule } from "@intentius/chant-lexicon-prometheus";
+
+// Error ratio over two windows, and an alert that needs both to agree.
+const windows = ["5m", "1h"];
+
+const recording: Rule[] = windows.map((w) => ({
+  record: \`job:http_errors:ratio\${w}\`,
+  expr: \`sum by (job) (rate(http_requests_total{code=~"5.."}[\${w}])) / sum by (job) (rate(http_requests_total[\${w}]))\`,
+}));
+
+const alerting: Rule[] = [
+  {
+    alert: "ErrorBudgetBurn",
+    expr: "job:http_errors:ratio1h > (14.4 * 0.001) and job:http_errors:ratio5m > (14.4 * 0.001)",
+    labels: { severity: "page" },
+    annotations: { summary: "{{ $labels.job }} is burning its error budget 14.4x too fast" },
+  },
+];
+
+const errorRatios = new RuleGroup({ name: "error-ratios", rules: recording });
+const burnAlerts = new RuleGroup({ name: "burn-alerts", rules: alerting });
+
+export { errorRatios, burnAlerts };
+`;
+
+export function initTemplates(template?: string): InitTemplateSet {
+  if (template === "rules") return { src: { "rules.ts": RULES } };
+  if (template === "slo-style") return { src: { "rules.ts": SLO_STYLE } };
+  return { src: { "rules.ts": RULES, "alertmanager.ts": ALERTMANAGER } };
+}

package/src/lint/audit-catalog.ts

@@ -0,0 +1,123 @@
+/**
+ * The prometheus lexicon's chant audit catalog, contributed via
+ * `prometheusPlugin.auditCatalog()` (#687, #1346).
+ *
+ * Every post-synth check reads the emitted rule file or `alertmanager.yml`
+ * (or any output document shaped like one), so they are all `yamlBased` and
+ * fire on an audit of standalone files too. The three source-level lint rules
+ * read TypeScript, so they are constructed with `yamlBased: false`; they are
+ * listed for a reader who meets them in a lint report.
+ */
+
+import { auditRule, type RuleMeta } from "@intentius/chant/audit/catalog";
+
+function sourceRule(id: string, category: RuleMeta["category"], title: string, remediation: string): RuleMeta {
+  return { id, tier: "merge-worthy", fixKind: "guidance", category, title, remediation, yamlBased: false };
+}
+
+function outputRule(
+  id: string,
+  tier: RuleMeta["tier"],
+  category: NonNullable<RuleMeta["category"]>,
+  title: string,
+  remediation: string,
+): RuleMeta {
+  return auditRule(id, tier, "guidance", title, remediation, { category });
+}
+
+export const prometheusAuditCatalog: Record<string, RuleMeta> = {
+  PROM001: sourceRule(
+    "PROM001",
+    "security",
+    "Alertmanager credential declared as a literal",
+    "Mount the secret as a file and set the field's *_file sibling (api_url_file, routing_key_file, auth_password_file, credentials_file) instead.",
+  ),
+  PROM002: sourceRule(
+    "PROM002",
+    "correctness",
+    "Literal PromQL expression in a RuleGroup does not parse",
+    "Fix the expression at the offset the message names.",
+  ),
+  PROM003: sourceRule(
+    "PROM003",
+    "correctness",
+    "Slo objective, window or SLI expression is invalid",
+    "Set objective strictly between 0 and 1, window to a Prometheus duration such as 28d, and write each SLI expression as PromQL with {{window}} where the range goes.",
+  ),
+  PROM101: outputRule("PROM101", "merge-worthy", "correctness", "Rule group name repeated in a rule file", "Give every group in the rule file its own name."),
+  PROM102: outputRule(
+    "PROM102",
+    "report-only",
+    "correctness",
+    "Two rules share a name and label set",
+    "Rename one rule, or give the two different labels (for alerts, usually a different severity).",
+  ),
+  PROM103: outputRule(
+    "PROM103",
+    "merge-worthy",
+    "correctness",
+    "Rule or group duration is not a Prometheus duration",
+    "Write durations as <number><unit> terms in descending order, e.g. 30s, 5m, 1h30m.",
+  ),
+  PROM104: outputRule("PROM104", "merge-worthy", "correctness", "Rule expression is not valid PromQL", "Fix the expression at the offset the message names."),
+  PROM105: outputRule(
+    "PROM105",
+    "merge-worthy",
+    "correctness",
+    "Rule or group is malformed",
+    "Set exactly one of record or alert with a non-empty name; keep for, keep_firing_for and annotations to alerting rules.",
+  ),
+  PROM106: outputRule(
+    "PROM106",
+    "report-only",
+    "best-practice",
+    "Alerting rule has no severity label",
+    "Add a severity label (on the rule or the group) that an Alertmanager route matches.",
+  ),
+  PROM107: outputRule(
+    "PROM107",
+    "report-only",
+    "best-practice",
+    "Alerting rule has no summary or description",
+    "Add a summary annotation saying what is wrong, and a description or runbook_url saying what to do.",
+  ),
+  PROM201: outputRule("PROM201", "merge-worthy", "correctness", "Route sends to an undeclared receiver", "Declare the receiver, or reference the declared Receiver entity instead of a name string."),
+  PROM202: outputRule(
+    "PROM202",
+    "merge-worthy",
+    "correctness",
+    "Alert severity not routed by any route",
+    "Add a route matching the severity (e.g. severity=\"page\") below the root, or change the alert's severity to one that is routed.",
+  ),
+  PROM203: outputRule("PROM203", "merge-worthy", "correctness", "Receiver or time interval name repeated", "Give every receiver and every time interval its own name."),
+  PROM204: outputRule(
+    "PROM204",
+    "merge-worthy",
+    "correctness",
+    "Route names an undeclared time interval",
+    "Declare the TimeInterval, or reference the declared entity instead of a name string.",
+  ),
+  PROM205: outputRule(
+    "PROM205",
+    "merge-worthy",
+    "correctness",
+    "Root route missing, without a receiver, or with matchers",
+    "Declare exactly one root Route with a receiver and no matchers, and nest every other route under it.",
+  ),
+  PROM206: outputRule("PROM206", "merge-worthy", "correctness", "Matcher does not parse", 'Write matchers as label, operator and quoted value, e.g. severity="page" or team=~"db|infra".'),
+  PROM207: outputRule("PROM207", "report-only", "best-practice", "Receiver declared but never routed to", "Route to the receiver, or remove it."),
+  PROM208: outputRule(
+    "PROM208",
+    "merge-worthy",
+    "correctness",
+    "Alertmanager duration is not a duration",
+    "Write durations as <number><unit> terms in descending order, e.g. 30s, 5m, 4h.",
+  ),
+  PROM209: outputRule(
+    "PROM209",
+    "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).",
+  ),
+};

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

@@ -0,0 +1,37 @@
+// Code generated by chant generate. DO NOT EDIT.
+import type { PostSynthCheck } from "@intentius/chant/lint/post-synth";
+import { prom101 } from "./prom101";
+import { prom102 } from "./prom102";
+import { prom103 } from "./prom103";
+import { prom104 } from "./prom104";
+import { prom105 } from "./prom105";
+import { prom106 } from "./prom106";
+import { prom107 } from "./prom107";
+import { prom201 } from "./prom201";
+import { prom202 } from "./prom202";
+import { prom203 } from "./prom203";
+import { prom204 } from "./prom204";
+import { prom205 } from "./prom205";
+import { prom206 } from "./prom206";
+import { prom207 } from "./prom207";
+import { prom208 } from "./prom208";
+import { prom209 } from "./prom209";
+
+export const postSynthChecks: PostSynthCheck[] = [
+  prom101,
+  prom102,
+  prom103,
+  prom104,
+  prom105,
+  prom106,
+  prom107,
+  prom201,
+  prom202,
+  prom203,
+  prom204,
+  prom205,
+  prom206,
+  prom207,
+  prom208,
+  prom209,
+];

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

@@ -0,0 +1,256 @@
+import { describe, expect, test } from "vitest";
+import { makePostSynthCtx, makePostSynthCtxFromFiles } from "@intentius/chant-test-utils";
+import { postSynthChecks } from "./index";
+import { prom101 } from "./prom101";
+import { prom102 } from "./prom102";
+import { prom103 } from "./prom103";
+import { prom104 } from "./prom104";
+import { prom105 } from "./prom105";
+import { prom106 } from "./prom106";
+import { prom107 } from "./prom107";
+import { prom201 } from "./prom201";
+import { prom202 } from "./prom202";
+import { prom203 } from "./prom203";
+import { prom204 } from "./prom204";
+import { prom205 } from "./prom205";
+import { prom206 } from "./prom206";
+import { prom207 } from "./prom207";
+import { prom208 } from "./prom208";
+import { prom209 } from "./prom209";
+
+const RULES = `groups:
+  - name: api
+    interval: 30s
+    rules:
+      - record: job:http_errors:ratio5m
+        expr: sum by (job) (rate(http_requests_total{code=~"5.."}[5m])) / sum by (job) (rate(http_requests_total[5m]))
+      - alert: ApiErrors
+        expr: job:http_errors:ratio5m > 0.05
+        for: 10m
+        labels:
+          severity: page
+        annotations:
+          summary: errors
+      - alert: ApiErrors
+        expr: job:http_errors:ratio5m > 0.01
+        for: 1h
+        labels:
+          severity: ticket
+        annotations:
+          summary: errors
+`;
+
+const AM = `global:
+  resolve_timeout: 5m
+route:
+  receiver: default
+  group_by: [alertname]
+  routes:
+    - receiver: oncall
+      matchers: ['severity="page"']
+    - receiver: default
+      matchers: ['severity=~"ticket|info"']
+      mute_time_intervals: [weekend]
+inhibit_rules:
+  - source_matchers: ['severity="page"']
+    target_matchers: ['severity="ticket"']
+    equal: [alertname]
+receivers:
+  - name: default
+    webhook_configs:
+      - url: "http://sink:8080/"
+  - name: oncall
+    pagerduty_configs:
+      - routing_key_file: /etc/pd
+time_intervals:
+  - name: weekend
+    time_intervals:
+      - weekdays: [saturday, sunday]
+`;
+
+const both = (rules = RULES, am = AM) => makePostSynthCtxFromFiles("prometheus", { "alertmanager.yml": am }, rules);
+const rulesOnly = (rules: string) => makePostSynthCtx("prometheus", rules);
+const amOnly = (am: string) => makePostSynthCtx("prometheus", am);
+
+describe("a clean rule file and alertmanager.yml", () => {
+  test.each(postSynthChecks.map((c) => [c.id, c] as const))("%s finds nothing", (_id, check) => {
+    expect(check.check(both())).toEqual([]);
+  });
+});
+
+describe("rule file checks", () => {
+  test("PROM101 repeated group name", () => {
+    const diags = prom101.check(rulesOnly(`${RULES}  - name: api\n    rules: []\n`));
+    expect(diags).toHaveLength(1);
+    expect(diags[0]).toMatchObject({ checkId: "PROM101", severity: "error", entity: "api" });
+  });
+
+  test("PROM102 same name and labels, but not same name with a different severity", () => {
+    const dup = RULES.replace("severity: ticket", "severity: page");
+    expect(prom102.check(rulesOnly(dup)).map((d) => d.entity)).toEqual(["api/ApiErrors"]);
+    expect(prom102.check(rulesOnly(RULES))).toEqual([]);
+  });
+
+  test("PROM102 counts group labels", () => {
+    const text = `groups:
+  - name: a
+    labels: {team: x}
+    rules:
+      - record: r
+        expr: "1"
+  - name: b
+    rules:
+      - record: r
+        expr: "1"
+        labels: {team: x}
+`;
+    expect(prom102.check(rulesOnly(text))).toHaveLength(1);
+  });
+
+  test("PROM103 bad durations on the group and the rule", () => {
+    const bad = RULES.replace("interval: 30s", "interval: 30 seconds").replace("for: 10m", "for: 1.5h");
+    expect(prom103.check(rulesOnly(bad)).map((d) => d.message)).toEqual([
+      'group "api" interval "30 seconds" is not a Prometheus duration (e.g. 30s, 1m, 1h30m)',
+      'rule api/ApiErrors for "1.5h" is not a Prometheus duration (e.g. 5m, 1h)',
+    ]);
+  });
+
+  test("PROM104 PromQL syntax", () => {
+    const bad = RULES.replace("expr: job:http_errors:ratio5m > 0.05", "expr: job:http_errors:ratio5m >");
+    const diags = prom104.check(rulesOnly(bad));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].entity).toBe("api/ApiErrors");
+    expect(diags[0].message).toContain("ends early");
+  });
+
+  test("PROM105 malformed rules", () => {
+    const text = `groups:
+  - name: g
+    rules:
+      - record: a:b
+        expr: "1"
+        for: 5m
+      - expr: "1"
+      - record: x
+        alert: y
+        expr: "1"
+`;
+    const diags = prom105.check(rulesOnly(text));
+    expect(diags.map((d) => d.message)).toEqual([
+      "recording rule g/a:b sets for, which only alerting rules take",
+      "rule g/rule 2 sets neither record nor alert",
+      "rule g/x sets both record and alert; a rule is one or the other",
+    ]);
+  });
+
+  test("PROM106 no severity, unless the group carries one", () => {
+    const noSev = RULES.replace("        labels:\n          severity: page\n", "");
+    expect(prom106.check(rulesOnly(noSev)).map((d) => d.entity)).toEqual(["api/ApiErrors"]);
+    const groupSev = noSev.replace("    interval: 30s\n", "    interval: 30s\n    labels:\n      severity: page\n");
+    expect(prom106.check(rulesOnly(groupSev))).toEqual([]);
+  });
+
+  test("PROM107 no summary or description", () => {
+    const bare = RULES.replace("        annotations:\n          summary: errors\n", "");
+    expect(prom107.check(rulesOnly(bare))).toHaveLength(1);
+  });
+});
+
+describe("alertmanager checks", () => {
+  test("PROM201 route to an undeclared receiver", () => {
+    const diags = prom201.check(amOnly(AM.replace("  - receiver: oncall", "  - receiver: on-call")));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain('receiver "on-call"');
+    expect(diags[0].entity).toBe("route.routes[0]");
+  });
+
+  test("PROM202 an alert severity no route matches", () => {
+    const rules = RULES.replace("severity: ticket", "severity: warning");
+    const diags = prom202.check(both(rules));
+    expect(diags).toHaveLength(1);
+    expect(diags[0]).toMatchObject({ checkId: "PROM202", severity: "warning", entity: "warning" });
+    expect(diags[0].message).toContain("api/ApiErrors");
+  });
+
+  test("PROM202 reads regexes and negative matchers, and nested routes", () => {
+    const am = AM.replace(`    - receiver: default
+      matchers: ['severity=~"ticket|info"']
+      mute_time_intervals: [weekend]`, `    - receiver: default
+      matchers: ['team="x"']
+      routes:
+        - receiver: default
+          matchers: ['severity!="page"']`);
+    expect(prom202.check(both(RULES, am))).toEqual([]);
+  });
+
+  test("PROM202 is silent without rules or without an alertmanager config (chant #1939)", () => {
+    expect(prom202.check(rulesOnly(RULES.replace("severity: ticket", "severity: nope")))).toEqual([]);
+    expect(prom202.check(amOnly(AM))).toEqual([]);
+  });
+
+  test("PROM203 repeated receiver and interval names", () => {
+    const dup = AM.replace("time_intervals:\n  - name: weekend", "time_intervals:\n  - name: weekend\n    time_intervals: []\n  - name: weekend") + "  - name: default\n";
+    const am = dup.replace("receivers:\n", "receivers:\n  - name: oncall\n");
+    const diags = prom203.check(amOnly(am));
+    expect(diags.map((d) => d.entity).sort()).toEqual(["oncall", "weekend"]);
+  });
+
+  test("PROM204 an undeclared time interval", () => {
+    const diags = prom204.check(amOnly(AM.replace("mute_time_intervals: [weekend]", "mute_time_intervals: [weekends]")));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain('"weekends"');
+  });
+
+  test("PROM205 root route shape", () => {
+    expect(prom205.check(amOnly("receivers:\n  - name: a\n")).map((d) => d.message)[0]).toContain("no root route");
+    expect(prom205.check(amOnly(AM.replace("  receiver: default\n  group_by", "  group_by")))[0].message).toContain("no receiver");
+    expect(prom205.check(amOnly(AM.replace("  group_by: [alertname]", "  group_by: [alertname]\n  matchers: ['a=\"b\"']")))[0].message).toContain(
+      "has matchers",
+    );
+  });
+
+  test("PROM206 unparseable matchers in routes and inhibit rules", () => {
+    const bad = AM.replace(`matchers: ['severity="page"']`, `matchers: ['severity']`).replace(
+      `target_matchers: ['severity="ticket"']`,
+      `target_matchers: ['severity=~"("']`,
+    );
+    expect(prom206.check(amOnly(bad)).map((d) => d.entity)).toEqual(["route.routes[0]", "inhibit_rules[0]"]);
+  });
+
+  test("PROM207 an unused receiver", () => {
+    const diags = prom207.check(amOnly(`${AM.replace("\ntime_intervals:", "\n  - name: spare\ntime_intervals:")}`));
+    expect(diags.map((d) => d.entity)).toEqual(["spare"]);
+  });
+
+  test("PROM208 bad Alertmanager durations", () => {
+    const bad = AM.replace("resolve_timeout: 5m", "resolve_timeout: five").replace("group_by: [alertname]", "group_by: [alertname]\n  group_wait: 30sec");
+    expect(prom208.check(amOnly(bad)).map((d) => d.entity).sort()).toEqual(["global", "route"]);
+  });
+
+  test("PROM209 integrations missing their destination", () => {
+    const am = `route:
+  receiver: all
+receivers:
+  - name: all
+    webhook_configs: [{}]
+    slack_configs: [{channel: "#a"}]
+    pagerduty_configs: [{}]
+    email_configs: [{to: a@b.c}]
+`;
+    const msgs = prom209.check(amOnly(am)).map((d) => d.message);
+    expect(msgs).toHaveLength(5);
+    expect(msgs.join("\n")).toContain("smarthost");
+    const withGlobals = `global:\n  slack_api_url_file: /etc/slack\n  smtp_smarthost: "smtp:25"\n  smtp_from: am@b.c\n${am}`;
+    expect(prom209.check(amOnly(withGlobals)).map((d) => d.message)).toHaveLength(2);
+  });
+});
+
+describe("documents from other lexicons", () => {
+  test("a k8s manifest and a collector config are not read as ours", () => {
+    const ctx = makePostSynthCtx(
+      "k8s",
+      `apiVersion: v1\nkind: ConfigMap\nmetadata:\n  name: x\n---\nreceivers:\n  otlp: {}\nservice:\n  pipelines: {}\n`,
+    );
+    for (const check of postSynthChecks) expect(check.check(ctx)).toEqual([]);
+  });
+});

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

@@ -0,0 +1,89 @@
+/**
+ * Shared plumbing for the prometheus post-synth checks: find the rule files
+ * and `alertmanager.yml` documents in a build's output, and run the
+ * plain-function checks over them.
+ *
+ * Documents are recognized by shape, not by which lexicon emitted them, so a
+ * rule file that reaches the output some other way (a hand-written YAML
+ * sidecar) is checked too. `PrometheusRule` manifests are not read here;
+ * their groups are the same `RuleGroup`s and are checked where they are
+ * declared.
+ */
+
+import type { PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import type { SerializerResult } from "@intentius/chant/serializer";
+import { loadAll } from "js-yaml";
+import { looksLikeAlertmanagerConfig, looksLikeRuleFile, type AlertmanagerConfig, type RuleFileConfig } from "../../model";
+import {
+  validateAlertmanagerConfig,
+  validateRuleFile,
+  validateSeverityRouting,
+  type PrometheusIssue,
+  type PrometheusIssueCode,
+} from "../../validate-config";
+
+export interface FoundDocs {
+  ruleFiles: Array<{ source: string; config: RuleFileConfig }>;
+  alertmanager: Array<{ source: string; config: AlertmanagerConfig }>;
+}
+
+/** Every rule file and Alertmanager config in the output. Parsed with js-yaml rather than `ctx.docs`, which keeps block scalars and flow lists as strings. */
+export function prometheusDocs(ctx: PostSynthContext): FoundDocs {
+  const found: FoundDocs = { ruleFiles: [], alertmanager: [] };
+  for (const [lexicon, output] of ctx.outputs) {
+    const texts: Array<[string, string]> =
+      typeof output === "string"
+        ? [[lexicon, output]]
+        : [[lexicon, (output as SerializerResult).primary], ...Object.entries((output as SerializerResult).files ?? {})];
+    for (const [source, text] of texts) {
+      if (!text) continue;
+      let docs: unknown[];
+      try {
+        docs = loadAll(text);
+      } catch {
+        continue; // not YAML, or not ours
+      }
+      for (const doc of docs) {
+        if (looksLikeRuleFile(doc)) found.ruleFiles.push({ source, config: doc });
+        else if (looksLikeAlertmanagerConfig(doc)) found.alertmanager.push({ source, config: doc });
+      }
+    }
+  }
+  return found;
+}
+
+function toDiagnostic(issue: PrometheusIssue, source: string): PostSynthDiagnostic {
+  return {
+    checkId: issue.code,
+    severity: issue.severity,
+    message: source && source !== "prometheus" ? `${source}: ${issue.message}` : issue.message,
+    ...(issue.subject ? { entity: issue.subject } : {}),
+    lexicon: "prometheus",
+  };
+}
+
+/** Diagnostics for one rule-file code (PROM101-PROM107) across every rule file in the output. */
+export function ruleFileDiagnostics(ctx: PostSynthContext, code: PrometheusIssueCode): PostSynthDiagnostic[] {
+  return prometheusDocs(ctx).ruleFiles.flatMap(({ source, config }) =>
+    validateRuleFile(config)
+      .filter((i) => i.code === code)
+      .map((i) => toDiagnostic(i, source)),
+  );
+}
+
+/** Diagnostics for one Alertmanager code (PROM201, PROM203-PROM209) across every `alertmanager.yml` in the output. */
+export function alertmanagerDiagnostics(ctx: PostSynthContext, code: PrometheusIssueCode): PostSynthDiagnostic[] {
+  return prometheusDocs(ctx).alertmanager.flatMap(({ source, config }) =>
+    validateAlertmanagerConfig(config)
+      .filter((i) => i.code === code)
+      .map((i) => toDiagnostic(i, source)),
+  );
+}
+
+/** PROM202: joins every rule file in the output against every Alertmanager config in it. Silent when either is absent. */
+export function routingDiagnostics(ctx: PostSynthContext): PostSynthDiagnostic[] {
+  const { ruleFiles, alertmanager } = prometheusDocs(ctx);
+  if (ruleFiles.length === 0) return [];
+  const files = ruleFiles.map((r) => r.config);
+  return alertmanager.flatMap(({ source, config }) => validateSeverityRouting(files, config).map((i) => toDiagnostic(i, source)));
+}

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

@@ -0,0 +1,17 @@
+/**
+ * PROM101: Two rule groups in one rule file share a name
+ *
+ * Prometheus refuses to load a rule file whose group names repeat.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { ruleFileDiagnostics } from "./prom-helpers";
+
+export const prom101: PostSynthCheck = {
+  id: "PROM101",
+  description: "Two rule groups in one rule file share a name",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return ruleFileDiagnostics(ctx, "PROM101");
+  },
+};

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

@@ -0,0 +1,17 @@
+/**
+ * PROM102: Two rules share a name and label set
+ *
+ * Two recording rules (or two alerts) with the same name and labels produce the same series and overwrite each other. This follows promtool's duplicate-rules lint: alerts that share a name and differ by a label, such as severity, are fine.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { ruleFileDiagnostics } from "./prom-helpers";
+
+export const prom102: PostSynthCheck = {
+  id: "PROM102",
+  description: "Two rules share a name and label set",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return ruleFileDiagnostics(ctx, "PROM102");
+  },
+};

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

@@ -0,0 +1,17 @@
+/**
+ * PROM103: A rule or group duration is not a Prometheus duration
+ *
+ * for, keep_firing_for, interval and query_offset take durations such as 30s, 5m or 1h30m. Prometheus refuses the rule file otherwise.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { ruleFileDiagnostics } from "./prom-helpers";
+
+export const prom103: PostSynthCheck = {
+  id: "PROM103",
+  description: "A rule or group duration is not a Prometheus duration",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return ruleFileDiagnostics(ctx, "PROM103");
+  },
+};