@intentius/chant-lexicon-prometheus 0.124.31 → 0.124.33

package/dist/lint/rules/slo-literal.js

@@ -0,0 +1,79 @@
+import { ts } from "@intentius/chant/lint/typescript";
+import { calleeName, literalText, position, propertyName } from "./prom-ast.js";
+import { sliExprProblem } from "../../composites/slo.js";
+import { durationMs, isValidDuration } from "../../duration.js";
+/** A numeric literal, with an optional leading minus, as a number. */
+function literalNumber(node) {
+    if (ts.isNumericLiteral(node))
+        return Number(node.text);
+    if (ts.isPrefixUnaryExpression(node) && node.operator === ts.SyntaxKind.MinusToken && ts.isNumericLiteral(node.operand)) {
+        return -Number(node.operand.text);
+    }
+    return undefined;
+}
+function objectProps(node) {
+    const out = new Map();
+    if (!ts.isObjectLiteralExpression(node))
+        return out;
+    for (const p of node.properties) {
+        const name = propertyName(p);
+        if (name !== undefined && ts.isPropertyAssignment(p))
+            out.set(name, p.initializer);
+    }
+    return out;
+}
+/**
+ * PROM003: an `Slo` whose literal objective, window or SLI expression can
+ * not build.
+ *
+ * `Slo()` throws on the same problems when the build runs it; this rule
+ * reports them in the editor, at the literal: an objective outside (0, 1),
+ * a window that is not a positive Prometheus duration, and an SLI
+ * expression without `{{window}}` or that is not PromQL once it is filled
+ * in. Values built at runtime are left to the constructor.
+ */
+export const sloLiteralRule = {
+    id: "PROM003",
+    severity: "error",
+    category: "correctness",
+    description: "An Slo's literal objective, window or SLI expression is invalid",
+    check(context) {
+        const diagnostics = [];
+        const source = context.sourceFile;
+        const report = (node, message) => diagnostics.push({ ruleId: "PROM003", severity: "error", message, file: context.filePath, ...position(source, node) });
+        const visit = (node) => {
+            if ((ts.isCallExpression(node) || ts.isNewExpression(node)) && calleeName(node) === "Slo") {
+                const arg = node.arguments?.[0];
+                if (arg) {
+                    const props = objectProps(arg);
+                    const objective = props.get("objective");
+                    const o = objective ? literalNumber(objective) : undefined;
+                    if (objective && o !== undefined && !(o > 0 && o < 1)) {
+                        report(objective, `Slo objective must be strictly between 0 and 1 (e.g. 0.995 for 99.5%), got ${o}`);
+                    }
+                    const window = props.get("window");
+                    const w = window ? literalText(window) : undefined;
+                    if (window && w !== undefined && (!isValidDuration(w) || durationMs(w) === 0)) {
+                        report(window, `Slo window must be a positive Prometheus duration (e.g. 28d or 30d), got ${JSON.stringify(w)}`);
+                    }
+                    const sli = props.get("sli");
+                    if (sli) {
+                        for (const [key, expr] of objectProps(sli)) {
+                            if (key !== "good" && key !== "errors" && key !== "total")
+                                continue;
+                            const text = literalText(expr);
+                            if (text === undefined)
+                                continue;
+                            const problem = sliExprProblem(text);
+                            if (problem)
+                                report(expr, `Slo sli.${key} ${problem}`);
+                        }
+                    }
+                }
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(source);
+        return diagnostics;
+    },
+};

package/dist/lsp/completions.js

@@ -0,0 +1,11 @@
+import { LexiconIndex, lexiconCompletions } from "@intentius/chant/lsp/lexicon-providers";
+import { lexiconRegistry } from "../catalog.js";
+let cachedIndex = null;
+function getIndex() {
+    cachedIndex ?? (cachedIndex = new LexiconIndex(lexiconRegistry()));
+    return cachedIndex;
+}
+/** Completions for the prometheus entity classes: RuleGroup and the Alertmanager kinds. */
+export function completions(ctx) {
+    return lexiconCompletions(ctx, getIndex(), "Prometheus entity");
+}

package/dist/lsp/hover.js

@@ -0,0 +1,21 @@
+import { LexiconIndex, lexiconHover } from "@intentius/chant/lsp/lexicon-providers";
+import { CATALOG, lexiconRegistry } from "../catalog.js";
+import { PROMETHEUS_PIN } from "../pin.js";
+let cachedIndex = null;
+function getIndex() {
+    cachedIndex ?? (cachedIndex = new LexiconIndex(lexiconRegistry()));
+    return cachedIndex;
+}
+/** Hover for prometheus entity classes: what the entity is and which file it lands in. */
+export function hover(ctx) {
+    return lexiconHover(ctx, getIndex(), resourceHover);
+}
+function resourceHover(className, entry) {
+    const cat = CATALOG.find((c) => c.className === className);
+    const lines = [`**${className}**`, "", `prometheus type: \`${entry.resourceType}\``];
+    if (cat) {
+        const pin = cat.file === "rule file" ? PROMETHEUS_PIN.prometheus : PROMETHEUS_PIN.alertmanager;
+        lines.push("", cat.description, "", `Serializes into the ${cat.file}. Typed against ${pin.source} ${pin.version}.`);
+    }
+    return { contents: lines.join("\n") };
+}

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "prometheus",
-  "version": "0.124.31",
+  "version": "0.124.33",
   "chantVersion": ">=0.1.0",
   "namespace": "Prometheus",
   "intrinsics": [],

package/dist/matchers.js

@@ -0,0 +1,131 @@
+/**
+ * Alertmanager label matchers: `severity="critical"`, `team=~"db|infra"`,
+ * `env!="dev"`.
+ *
+ * A matcher is a label name, an operator (`=`, `!=`, `=~`, `!~`) and a value,
+ * quoted or not. One list entry may also hold several comma-separated
+ * matchers in braces (`{a="1", b="2"}`), which Alertmanager accepts too.
+ * Regex values are anchored at both ends, as Alertmanager anchors them.
+ */
+const NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function readQuoted(s, start) {
+    let i = start + 1;
+    let out = "";
+    while (i < s.length) {
+        const c = s[i];
+        if (c === "\\") {
+            const next = s[i + 1];
+            if (next === undefined)
+                return undefined;
+            out += next === "n" ? "\n" : next === "t" ? "\t" : next;
+            i += 2;
+            continue;
+        }
+        if (c === '"')
+            return { value: out, end: i + 1 };
+        out += c;
+        i++;
+    }
+    return undefined;
+}
+function parseOne(text) {
+    const s = text.trim();
+    const opMatch = /(=~|!~|!=|=)/.exec(s);
+    if (!opMatch)
+        return `"${s}" has no operator; use =, !=, =~ or !~`;
+    let name = s.slice(0, opMatch.index).trim();
+    if (name.startsWith('"') && name.endsWith('"') && name.length >= 2)
+        name = name.slice(1, -1);
+    else if (!NAME.test(name))
+        return `"${name}" is not a label name`;
+    if (name === "")
+        return `"${s}" has an empty label name`;
+    const op = opMatch[1];
+    const rest = s.slice(opMatch.index + op.length).trim();
+    let value;
+    if (rest.startsWith('"')) {
+        const q = readQuoted(rest, 0);
+        if (!q)
+            return `"${s}" has an unterminated quoted value`;
+        if (rest.slice(q.end).trim() !== "")
+            return `"${s}" has text after its quoted value`;
+        value = q.value;
+    }
+    else {
+        if (/["{}=!~,]/.test(rest))
+            return `"${s}" has an unquoted value with reserved characters; quote it`;
+        value = rest;
+    }
+    if (op === "=~" || op === "!~") {
+        try {
+            new RegExp(`^(?:${value})$`);
+        }
+        catch (err) {
+            return `"${s}" has an invalid regular expression: ${err instanceof Error ? err.message : String(err)}`;
+        }
+    }
+    return { name, op, value };
+}
+/** Split `a="x,y", b=z` on the commas that are outside quotes. */
+function splitTopLevel(s) {
+    const parts = [];
+    let depthQuote = false;
+    let cur = "";
+    for (let i = 0; i < s.length; i++) {
+        const c = s[i];
+        if (c === "\\" && depthQuote) {
+            cur += c + (s[i + 1] ?? "");
+            i++;
+            continue;
+        }
+        if (c === '"')
+            depthQuote = !depthQuote;
+        if (c === "," && !depthQuote) {
+            parts.push(cur);
+            cur = "";
+            continue;
+        }
+        cur += c;
+    }
+    parts.push(cur);
+    return parts.map((p) => p.trim()).filter((p) => p !== "");
+}
+/** Parse one entry of a `matchers:` list. */
+export function parseMatchers(entry) {
+    let s = entry.trim();
+    if (s === "")
+        return { ok: false, error: "empty matcher" };
+    if (s.startsWith("{")) {
+        if (!s.endsWith("}"))
+            return { ok: false, error: `"${entry}" opens a brace it never closes` };
+        s = s.slice(1, -1);
+    }
+    const matchers = [];
+    for (const part of splitTopLevel(s)) {
+        const m = parseOne(part);
+        if (typeof m === "string")
+            return { ok: false, error: m };
+        matchers.push(m);
+    }
+    if (matchers.length === 0)
+        return { ok: false, error: `"${entry}" holds no matcher` };
+    return { ok: true, matchers };
+}
+/** Whether one matcher matches a label set (a missing label reads as the empty string, as in Alertmanager). */
+export function matcherMatches(m, labels) {
+    const v = labels[m.name] ?? "";
+    switch (m.op) {
+        case "=":
+            return v === m.value;
+        case "!=":
+            return v !== m.value;
+        case "=~":
+            return new RegExp(`^(?:${m.value})$`).test(v);
+        case "!~":
+            return !new RegExp(`^(?:${m.value})$`).test(v);
+    }
+}
+/** Build the matcher string for `name op value`, quoting the value. */
+export function matcher(name, op, value) {
+    return `${name}${op}${JSON.stringify(value)}`;
+}

package/dist/model.js

@@ -0,0 +1,108 @@
+/**
+ * The plain-data model of a Prometheus rule file and an Alertmanager config.
+ *
+ * Everything else in this lexicon reads or writes these shapes: the serializer
+ * builds them from declared entities, the YAML emitter prints them, the checks
+ * validate them, and other lexicons (the k8s `PrometheusRule`, the SLO
+ * composite, Grafana panels) read them. They are exactly the files' own
+ * layouts, so a parsed rule file or `alertmanager.yml` already is one and
+ * needs no conversion.
+ *
+ * Field names keep the files' snake_case (`keep_firing_for`, `group_wait`),
+ * so a declaration reads the same as the file it produces and the upstream
+ * docs apply word for word.
+ */
+import { RECEIVER_INTEGRATION_TYPES, } from "./integrations.js";
+export function isRecordingRuleConfig(rule) {
+    return typeof rule === "object" && rule !== null && typeof rule.record === "string";
+}
+export function isAlertingRuleConfig(rule) {
+    return typeof rule === "object" && rule !== null && typeof rule.alert === "string";
+}
+/** The rule's name: `record` for a recording rule, `alert` for an alerting rule. */
+export function ruleName(rule) {
+    return isRecordingRuleConfig(rule) ? rule.record : rule.alert;
+}
+// ── Alertmanager ────────────────────────────────────────────────────
+export * from "./integrations.js";
+export * from "./config-model.js";
+/** Every `global:` field, as a list, for code that reads a parsed file. */
+export const ALERTMANAGER_GLOBAL_FIELDS = Object.freeze(Object.keys({
+    resolve_timeout: true,
+    http_config: true,
+    jira_api_url: true,
+    smtp_from: true,
+    smtp_hello: true,
+    smtp_smarthost: true,
+    smtp_auth_username: true,
+    smtp_auth_password: true,
+    smtp_auth_password_file: true,
+    smtp_auth_secret: true,
+    smtp_auth_secret_file: true,
+    smtp_auth_identity: true,
+    smtp_require_tls: true,
+    smtp_tls_config: true,
+    smtp_force_implicit_tls: true,
+    slack_api_url: true,
+    slack_api_url_file: true,
+    slack_app_token: true,
+    slack_app_token_file: true,
+    slack_app_url: true,
+    pagerduty_url: true,
+    opsgenie_api_url: true,
+    opsgenie_api_key: true,
+    opsgenie_api_key_file: true,
+    wechat_api_url: true,
+    wechat_api_secret: true,
+    wechat_api_secret_file: true,
+    wechat_api_corp_id: true,
+    victorops_api_url: true,
+    victorops_api_key: true,
+    victorops_api_key_file: true,
+    telegram_api_url: true,
+    telegram_bot_token: true,
+    telegram_bot_token_file: true,
+    webex_api_url: true,
+    rocketchat_api_url: true,
+    rocketchat_token: true,
+    rocketchat_token_file: true,
+    rocketchat_token_id: true,
+    rocketchat_token_id_file: true,
+    mattermost_webhook_url: true,
+    mattermost_webhook_url_file: true,
+}));
+/** The receiver integrations, every one Alertmanager defines. */
+export const RECEIVER_INTEGRATIONS = Object.keys(RECEIVER_INTEGRATION_TYPES);
+/** True when a parsed document has the shape of a Prometheus rule file. */
+export function looksLikeRuleFile(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const v = value;
+    const groups = v.groups;
+    if (!Array.isArray(groups))
+        return false;
+    // Grafana's alerting provisioning files also hold `groups:` of named rule lists. Prometheus reads rule
+    // files strictly (unknown keys are errors), so `apiVersion`, a group `folder` or a rule's `data` means Grafana.
+    if ("apiVersion" in v)
+        return false;
+    return groups.every((g) => {
+        if (typeof g !== "object" || g === null)
+            return false;
+        const group = g;
+        if (typeof group.name !== "string" || !Array.isArray(group.rules) || "folder" in group)
+            return false;
+        return !group.rules.some((r) => typeof r === "object" && r !== null && "data" in r);
+    });
+}
+/** True when a parsed document has the shape of an `alertmanager.yml`. */
+export function looksLikeAlertmanagerConfig(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const v = value;
+    const route = v.route;
+    const receivers = v.receivers;
+    const hasRoute = typeof route === "object" && route !== null && !Array.isArray(route);
+    const hasReceivers = Array.isArray(receivers);
+    // A k8s manifest never has both at the top level; a collector config has neither.
+    return (hasRoute || hasReceivers) && !("apiVersion" in v) && !("kind" in v);
+}

package/dist/op/activities/index.js

@@ -0,0 +1,20 @@
+/**
+ * prometheus Op activities (#3369), resolved by the core activity registry
+ * when a project's `chant.config.ts` lists the `prometheus` lexicon. Every
+ * function this module exports is an activity, bound by its export name, so
+ * the helpers behind them stay in their own files.
+ *
+ * - `promtoolCheckRules`, `promtoolTestRules`, `amtoolCheckConfig`: the
+ *   upstream tools over built files, failing the step when the tool is
+ *   missing or rejects the file.
+ * - `amtoolRoutesTest`: labels route to the expected receivers.
+ * - `alertmanagerSilence`, `alertmanagerUnsilence`: a silence around a
+ *   change, recorded so the final and `onFailure` phases can expire it.
+ * - `rulesLoadedObserve`: declared rule groups as the resources of a
+ *   `ConvergeOp({ observe })`.
+ * - `ruleAudit`: the step of `RuleAuditOp`.
+ */
+export { promtoolCheckRules, promtoolTestRules, amtoolCheckConfig, amtoolRoutesTest } from "./promtool.js";
+export { alertmanagerSilence, alertmanagerUnsilence } from "./silence.js";
+export { rulesLoadedObserve } from "./rules-loaded.js";
+export { ruleAudit } from "./rule-audit.js";

package/dist/op/activities/promtool.js

@@ -0,0 +1,87 @@
+/**
+ * `promtool` and `amtool` as Op steps (#3369), over the functions in
+ * `../../tools.ts`.
+ *
+ * Those functions report `ran: false` when the binary is missing, so tests
+ * and CI can skip them. A step does not: a check that did not run must not
+ * read as a check that passed, so a missing binary fails the step, and so
+ * does a file the tool rejects, with the tool's output as the message.
+ *
+ * Paths are relative to the working directory. `promtoolTestRules` writes
+ * the rule file as `rules.yml` beside each test file, so a test file's
+ * `rule_files:` names `rules.yml`; the tests `sloRuleTests()` generates
+ * from `Slo` declarations do.
+ */
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { nonRetryableFailure } from "@intentius/chant/op";
+import { defaultExec } from "@intentius/chant-lexicon-otel/op/activities/exec";
+import { amtoolCheckConfig as amtoolCheckConfigText, promtoolCheckRules as promtoolCheckRulesText, promtoolTestRules as promtoolTestRulesText, } from "../../tools.js";
+const list = (v) => (v === undefined ? [] : Array.isArray(v) ? v : [v]);
+const read = (path) => readFileSync(resolve(process.cwd(), path), "utf8");
+function settle(tool, files, r, bin) {
+    if (!r.ran)
+        throw new Error(`${bin} is not installed (or does not run): ${tool} did not check ${files.join(", ")}. Install it or set bin.`);
+    if (!r.ok)
+        throw nonRetryableFailure(`${tool} rejected ${files.join(", ")}:\n${r.output.trim()}`, "PrometheusToolRejected");
+    return { files, ok: true, output: r.output.trim() };
+}
+const promtoolBin = (bin) => bin ?? process.env.PROMTOOL ?? "promtool";
+const amtoolBin = (bin) => bin ?? process.env.AMTOOL ?? "amtool";
+/** `promtool check rules` over each rule file. */
+export async function promtoolCheckRules(args) {
+    const bin = promtoolBin(args.bin);
+    const files = list(args.rules);
+    if (files.length === 0)
+        throw new Error("promtoolCheckRules: no rule file given");
+    const outputs = [];
+    for (const file of files)
+        outputs.push(settle("promtool check rules", [file], promtoolCheckRulesText(read(file), bin), bin).output);
+    return { files, ok: true, output: outputs.join("\n") };
+}
+/** `promtool test rules` over the rule file, once per test file or inline test document. */
+export async function promtoolTestRules(args) {
+    const bin = promtoolBin(args.bin);
+    const rules = read(args.rules);
+    const docs = [
+        ...list(args.tests).map((f) => [f, read(f)]),
+        ...list(args.testYaml).map((y, i) => [`testYaml[${i}]`, y]),
+    ];
+    if (docs.length === 0)
+        throw new Error("promtoolTestRules: give tests or testYaml (or slos to the builder)");
+    const outputs = [];
+    for (const [name, yaml] of docs)
+        outputs.push(settle("promtool test rules", [args.rules, name], promtoolTestRulesText(rules, yaml, bin), bin).output);
+    return { files: [args.rules, ...list(args.tests)], ok: true, output: outputs.join("\n"), tests: docs.length };
+}
+/** `amtool check-config` over the Alertmanager config. */
+export async function amtoolCheckConfig(args) {
+    const bin = amtoolBin(args.bin);
+    return settle("amtool check-config", [args.config], amtoolCheckConfigText(read(args.config), bin), bin);
+}
+/**
+ * The receivers amtool printed: its last non-empty line, comma-separated
+ * (`oncall` or `oncall,tickets`).
+ */
+export function parseRoutesOutput(output) {
+    const lines = output.split("\n").map((l) => l.trim()).filter((l) => l !== "" && !/^warning/i.test(l));
+    const last = lines[lines.length - 1] ?? "";
+    return last.split(",").map((s) => s.trim()).filter(Boolean);
+}
+/** `amtool config routes test`: the labels route to the expected receivers, in order. */
+export async function amtoolRoutesTest(args) {
+    const exec = args._exec ?? defaultExec;
+    const bin = amtoolBin(args.bin);
+    const expected = list(args.expect);
+    const pairs = Object.entries(args.labels).map(([k, v]) => `${k}=${v}`);
+    const r = await exec(bin, ["config", "routes", "test", `--config.file=${resolve(process.cwd(), args.config)}`, ...pairs], { timeoutMs: 30000 });
+    if (r.code === null)
+        throw new Error(`could not run ${bin}: ${r.error ?? "not found"}. Install amtool or set bin.`);
+    if (r.code !== 0)
+        throw nonRetryableFailure(`amtool config routes test failed (exit ${r.code}):\n${(r.stdout + r.stderr).trim()}`, "PrometheusToolRejected");
+    const receivers = parseRoutesOutput(r.stdout);
+    if (receivers.join(",") !== expected.join(",")) {
+        throw nonRetryableFailure(`${pairs.join(" ")} routes to ${receivers.join(",") || "(none)"} in ${args.config}, expected ${expected.join(",")}`, "PrometheusRouteMismatch");
+    }
+    return { config: args.config, labels: args.labels, receivers, ok: true };
+}

package/dist/op/activities/rule-audit.js

@@ -0,0 +1,128 @@
+/**
+ * `ruleAudit`: what a live Prometheus says about its rules (#3369), the
+ * activity behind `RuleAuditOp`.
+ *
+ * - groups with health errors: every rule `/api/v1/rules` reports with
+ *   `health: "err"`, with its `lastError`.
+ * - alerts pending or firing past a threshold, from `/api/v1/alerts`: a
+ *   pending alert older than `pendingFor` is one whose `for` never
+ *   completes (a flapping condition), and a firing one older than
+ *   `firingFor` is one nobody is acting on.
+ * - selectors no live target emits: each distinct vector selector in the
+ *   loaded rules' expressions, queried as
+ *   `count(last_over_time(<selector>[<lookback>]))`. An empty answer means
+ *   the rule reads a series nothing writes (a renamed metric, a dropped
+ *   label, a target that is gone). Selectors over series the rules record
+ *   themselves, and over `ALERTS`, are left out. One query per selector, at
+ *   most `selectorBudget` of them; the rest are counted as unchecked.
+ *
+ * `mode` is `report` (return the findings) or `issue` (keep one open issue
+ * current with them).
+ */
+import { defaultRunner, stickyIssue } from "@intentius/chant-lexicon-otel/op/activities/github";
+import { durationMs } from "../../duration.js";
+import { selectors } from "../../promql-analysis.js";
+import { fetchRuleGroups, prometheusUrl } from "./rules-loaded.js";
+async function getJson(f, url) {
+    const res = await f(url, { signal: AbortSignal.timeout(15000) });
+    if (!res.ok)
+        throw new Error(`GET ${url}: HTTP ${res.status}`);
+    const body = (await res.json());
+    if (body.status !== "success" || body.data === undefined)
+        throw new Error(`GET ${url}: status ${body.status ?? "missing"}`);
+    return body.data;
+}
+/** The distinct selectors the rules read, without the ones over recorded series and ALERTS. */
+export function auditedSelectors(groups) {
+    const recorded = new Set(["ALERTS", "ALERTS_FOR_STATE"]);
+    for (const g of groups)
+        for (const r of g.rules ?? [])
+            if (r.type === "recording")
+                recorded.add(r.name);
+    const out = new Set();
+    for (const g of groups) {
+        for (const r of g.rules ?? []) {
+            if (!r.query)
+                continue;
+            for (const s of selectors(r.query)) {
+                if (s.name && recorded.has(s.name))
+                    continue;
+                out.add(s.text.replace(/\s+/g, ""));
+            }
+        }
+    }
+    return [...out].sort();
+}
+function alertName(a) {
+    const { alertname, ...rest } = a.labels;
+    const extra = Object.entries(rest)
+        .sort(([x], [y]) => x.localeCompare(y))
+        .map(([k, v]) => `${k}="${v}"`)
+        .join(",");
+    return `${alertname ?? "(unnamed)"}{${extra}}`;
+}
+export function renderRuleAuditSummary(findings, queried, unchecked) {
+    let out = "## Prometheus rule audit\n\n";
+    if (findings.length === 0)
+        out += "No findings.\n";
+    else {
+        out += "| Finding | Subject | Detail |\n|---|---|---|\n";
+        for (const f of findings)
+            out += `| ${f.kind} | \`${f.subject.replace(/\|/g, "\\|")}\` | ${f.detail.replace(/\|/g, "\\|")} |\n`;
+    }
+    out += `\n${queried} selector(s) queried${unchecked > 0 ? `, ${unchecked} left unchecked by the budget` : ""}.\n`;
+    return out;
+}
+/** Audit a live Prometheus's rules, alerts and selectors. */
+export async function ruleAudit(args = {}) {
+    const f = args._fetch ?? fetch;
+    const url = prometheusUrl(args.url);
+    const now = (args._now ?? (() => new Date()))().getTime();
+    const mode = args.mode ?? "report";
+    const findings = [];
+    const groups = await fetchRuleGroups(f, url);
+    for (const g of groups) {
+        const errored = (g.rules ?? []).filter((r) => r.health === "err");
+        for (const r of errored)
+            findings.push({ kind: "rule-error", subject: g.name, detail: `${r.name}: ${r.lastError || "health err"}` });
+    }
+    const pendingMs = durationMs(args.pendingFor ?? "1h");
+    const firingMs = durationMs(args.firingFor ?? "24h");
+    if (pendingMs === undefined || firingMs === undefined)
+        throw new Error("pendingFor and firingFor are Prometheus durations such as 1h");
+    const { alerts } = await getJson(f, `${url}/api/v1/alerts`);
+    for (const a of alerts) {
+        const since = a.activeAt ? Date.parse(a.activeAt) : NaN;
+        if (Number.isNaN(since))
+            continue;
+        const age = now - since;
+        const hours = (age / 3600000).toFixed(1);
+        if (a.state === "pending" && age > pendingMs)
+            findings.push({ kind: "pending-too-long", subject: alertName(a), detail: `pending for ${hours}h` });
+        if (a.state === "firing" && age > firingMs)
+            findings.push({ kind: "firing-too-long", subject: alertName(a), detail: `firing for ${hours}h` });
+    }
+    const lookback = args.lookback ?? "1h";
+    if (durationMs(lookback) === undefined)
+        throw new Error(`lookback ${JSON.stringify(lookback)} is not a Prometheus duration`);
+    const all = auditedSelectors(groups);
+    const budget = Math.max(0, args.selectorBudget ?? 50);
+    const checked = all.slice(0, budget);
+    for (const sel of checked) {
+        const query = `count(last_over_time(${sel}[${lookback}]))`;
+        try {
+            const data = await getJson(f, `${url}/api/v1/query?query=${encodeURIComponent(query)}`);
+            if (data.result.length === 0)
+                findings.push({ kind: "selector-no-series", subject: sel, detail: `no series in the last ${lookback}` });
+        }
+        catch {
+            // A query Prometheus refuses is not evidence the series is missing.
+        }
+    }
+    const summary = renderRuleAuditSummary(findings, checked.length, all.length - checked.length);
+    const result = { mode, findings, queried: checked.length, unchecked: all.length - checked.length, summary };
+    if (mode === "issue" && findings.length > 0) {
+        result.issueUrl = await stickyIssue(args._run ?? defaultRunner, process.cwd(), args.issueTitle ?? "prometheus: rule audit findings", summary);
+    }
+    return result;
+}

package/dist/op/activities/rules-loaded.js

@@ -0,0 +1,73 @@
+/**
+ * Declared rule groups as resources a `ConvergeOp` observes (#3369).
+ *
+ * `rulesLoadedObserve` reads `GET /api/v1/rules` and returns one resource
+ * per declared group:
+ *
+ * - `drifted` when Prometheus has not loaded the group (the rule file is not
+ *   mounted, did not parse, or the reload has not happened), or when a rule
+ *   in it has `health: "err"`, with the rule's `lastError` as the detail;
+ * - `in-sync` otherwise;
+ * - `unknown`, for every group, when the API cannot be read.
+ *
+ * The declared groups are `groups`, plus the groups of each rule file in
+ * `rules` (read on each tick, so a rebuilt file is what is observed).
+ * Prometheus is `url`, else `$PROMETHEUS_URL`, else `http://localhost:9090`.
+ */
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { load } from "js-yaml";
+export function prometheusUrl(url) {
+    return (url ?? process.env.PROMETHEUS_URL ?? "http://localhost:9090").replace(/\/+$/, "");
+}
+/** The group names in a rule file's text. */
+export function ruleFileGroups(text) {
+    const doc = load(text);
+    return (doc?.groups ?? []).map((g) => g?.name).filter((n) => typeof n === "string");
+}
+/** The declared groups, in order, without repeats. */
+export function declaredGroups(args, cwd = process.cwd()) {
+    const out = [...(args.groups ?? [])];
+    const files = args.rules === undefined ? [] : Array.isArray(args.rules) ? args.rules : [args.rules];
+    for (const f of files)
+        out.push(...ruleFileGroups(readFileSync(resolve(cwd, f), "utf8")));
+    return [...new Set(out)];
+}
+/** `GET /api/v1/rules`'s groups. Throws on anything but a successful answer. */
+export async function fetchRuleGroups(f, url, timeoutMs = 10000) {
+    const res = await f(`${url}/api/v1/rules`, { signal: AbortSignal.timeout(timeoutMs) });
+    if (!res.ok)
+        throw new Error(`GET ${url}/api/v1/rules: HTTP ${res.status}`);
+    const body = (await res.json());
+    if (body.status !== "success" || !Array.isArray(body.data?.groups))
+        throw new Error(`GET ${url}/api/v1/rules: status ${body.status ?? "missing"}`);
+    return body.data.groups;
+}
+/** The verdict for one declared group against the loaded groups. */
+export function groupVerdict(name, loaded) {
+    const matches = loaded.filter((g) => g.name === name);
+    if (matches.length === 0)
+        return { name, status: "drifted", detail: "group not loaded" };
+    const rules = matches.flatMap((g) => g.rules ?? []);
+    const errored = rules.filter((r) => r.health === "err");
+    if (errored.length > 0) {
+        return { name, status: "drifted", detail: errored.map((r) => `${r.name}: ${r.lastError || "health err"}`).join("; ") };
+    }
+    return { name, status: "in-sync", detail: `${rules.length} rule(s) loaded` };
+}
+/** Observe the declared rule groups: one resource per group. */
+export async function rulesLoadedObserve(args) {
+    const names = declaredGroups(args);
+    if (names.length === 0)
+        throw new Error("rulesLoadedObserve: no groups declared (give groups or rules)");
+    const url = prometheusUrl(args.url);
+    let loaded;
+    try {
+        loaded = await fetchRuleGroups(args._fetch ?? fetch, url, args.timeoutMs);
+    }
+    catch (err) {
+        const detail = `rules API unreadable: ${err.message}`;
+        return { resources: names.map((name) => ({ name, status: "unknown", detail })) };
+    }
+    return { resources: names.map((name) => groupVerdict(name, loaded)) };
+}