@intentius/chant-lexicon-prometheus 0.124.31 → 0.124.32

package/dist/api/evaluated.js

@@ -0,0 +1,86 @@
+/**
+ * What `/api/v1/rules` says about a group, mapped two ways (#3371): to the
+ * group's health for `describeResources`, and, for a plain Prometheus,
+ * which has no rule group API, back to the rule-file shape for import.
+ *
+ * The second mapping is lossy, and says so. `/api/v1/rules` reports rules
+ * as Prometheus evaluates them, not as the file wrote them: `query` is the
+ * expression as PromQL prints it, durations are seconds, and a group's
+ * `interval` is the one it runs on, the global `evaluation_interval` when
+ * the group set none. A group's `labels` and `query_offset` are not
+ * reported at all.
+ */
+import { formatDuration } from "../duration.js";
+/** A duration in seconds as Prometheus writes one; undefined for zero or a value that is not a number. */
+function seconds(v) {
+    if (typeof v !== "number" || !Number.isFinite(v) || v <= 0)
+        return undefined;
+    return formatDuration(Math.round(v * 1000));
+}
+function labelsOf(v) {
+    if (typeof v !== "object" || v === null || Array.isArray(v))
+        return undefined;
+    const entries = Object.entries(v).map(([k, x]) => [k, String(x)]);
+    return entries.length > 0 ? Object.fromEntries(entries) : undefined;
+}
+/** What the import of evaluated groups leaves out, said once per export. */
+export const EVALUATED_IMPORT_WARNING = "rule groups were read from /api/v1/rules, which reports them as Prometheus evaluates them: expressions are as PromQL prints them, " +
+    "a group's interval is the one it runs on (the global evaluation_interval when the group sets none), and group labels and query_offset are not reported";
+/** A group from `/api/v1/rules` in the rule-file shape. */
+export function evaluatedToRuleGroup(group) {
+    const rules = group.rules.map((r) => {
+        if (r.type === "recording") {
+            const labels = labelsOf(r.labels);
+            return { record: r.name, expr: r.query, ...(labels ? { labels } : {}) };
+        }
+        const labels = labelsOf(r.labels);
+        const annotations = labelsOf(r.annotations);
+        const forDuration = seconds(r.duration);
+        const keep = seconds(r.keepFiringFor);
+        return {
+            alert: r.name,
+            expr: r.query,
+            ...(forDuration ? { for: forDuration } : {}),
+            ...(keep ? { keep_firing_for: keep } : {}),
+            ...(labels ? { labels } : {}),
+            ...(annotations ? { annotations } : {}),
+        };
+    });
+    const interval = seconds(group.interval);
+    return {
+        name: group.name,
+        ...(interval ? { interval } : {}),
+        ...(typeof group.limit === "number" && group.limit > 0 ? { limit: group.limit } : {}),
+        rules,
+    };
+}
+export function groupHealth(group) {
+    let failing = 0;
+    let unknown = 0;
+    let firing = 0;
+    let pending = 0;
+    let lastError;
+    for (const r of group.rules) {
+        if (r.health === "err") {
+            failing++;
+            lastError ?? (lastError = `${r.name}: ${r.lastError ?? "evaluation failed"}`);
+        }
+        else if (r.health !== "ok")
+            unknown++;
+        if (r.state === "firing")
+            firing++;
+        else if (r.state === "pending")
+            pending++;
+    }
+    const health = failing > 0 ? "err" : unknown > 0 || group.rules.length === 0 ? "unknown" : "ok";
+    return {
+        health,
+        ...(lastError ? { lastError } : {}),
+        failing,
+        firing,
+        pending,
+        ...(group.lastEvaluation ? { lastEvaluation: group.lastEvaluation } : {}),
+        ...(typeof group.evaluationTime === "number" ? { evaluationTime: group.evaluationTime } : {}),
+        ...(typeof group.interval === "number" ? { interval: group.interval } : {}),
+    };
+}

package/dist/api/fake-servers.js

@@ -0,0 +1,165 @@
+/**
+ * A ruler and an Alertmanager in memory, for the observe and export tests
+ * (#3371), and for the ruler apply target's (#3372).
+ *
+ * Each fake is a request handler over a state the test sets up. It answers
+ * the routes ./ruler.ts and ./alertmanager.ts use, in the shapes the
+ * projects document: the ruler config API's YAML (a mapping of namespace to
+ * groups; one group alone at `/{namespace}/{group}`; 404 for a namespace or
+ * group that is not there), `/api/v1/rules` JSON, Alertmanager's
+ * `/api/v2/status` and Mimir's `/api/v1/alerts`. With `tenant` set it
+ * answers 401 to a request without that `X-Scope-OrgID`, as Mimir does
+ * ("no org id").
+ *
+ * {@link serveFake} puts a handler behind a real HTTP server on localhost,
+ * so a test drives the default `fetch` transport, headers included.
+ * {@link fakeHttp} hands the same handler in as a {@link PromHttp}.
+ */
+import { createServer } from "node:http";
+import { dump } from "js-yaml";
+import { loadPrometheusYaml } from "../import/parser.js";
+const yaml = (v) => dump(v, { lineWidth: -1, noRefs: true });
+const ok = (text, contentType = "application/yaml") => ({ status: 200, text, contentType });
+const json = (v) => ({ status: 200, text: JSON.stringify(v), contentType: "application/json" });
+const notFound = (what) => ({ status: 404, text: what, contentType: "text/plain" });
+function tenantRefused(tenant, req) {
+    if (tenant === undefined)
+        return undefined;
+    return req.headers["x-scope-orgid"] === tenant ? undefined : { status: 401, text: "no org id", contentType: "text/plain" };
+}
+/** What `/api/v1/rules` reports for a group nobody set an evaluation for: every rule healthy. */
+export function evaluatedOf(file, group) {
+    const rules = Array.isArray(group.rules) ? group.rules : [];
+    return {
+        name: group.name,
+        file,
+        interval: 60,
+        rules: rules.map((r) => typeof r.alert === "string"
+            ? { type: "alerting", name: r.alert, query: String(r.expr), duration: 0, labels: r.labels ?? {}, annotations: r.annotations ?? {}, health: "ok", state: "inactive" }
+            : { type: "recording", name: String(r.record), query: String(r.expr), labels: r.labels ?? {}, health: "ok" }),
+    };
+}
+/** A ruler over `state`. Writes change `state`, so a test can read back what an apply did. */
+export function fakeRuler(state, calls = []) {
+    const prefix = state.prometheusPrefix ?? (state.kind === "prometheus" ? "" : "/prometheus");
+    const base = state.kind === "mimir" ? `${prefix}/config/v1/rules` : state.kind === "cortex" ? "/api/v1/rules" : state.kind === "loki" ? "/loki/api/v1/rules" : undefined;
+    return (req) => {
+        var _a, _b;
+        calls.push(`${req.method} ${req.path}`);
+        if (state.status !== undefined)
+            return { status: state.status, text: "refused" };
+        const refused = tenantRefused(state.tenant, req);
+        if (refused)
+            return refused;
+        const route = req.path.split("?")[0];
+        if (route === `${prefix}/api/v1/rules` && req.method === "GET") {
+            if (state.evaluatedStatus !== undefined)
+                return { status: state.evaluatedStatus, text: "evaluation unavailable" };
+            const groups = state.evaluated ?? Object.entries(state.namespaces).flatMap(([ns, gs]) => gs.map((g) => evaluatedOf(ns, g)));
+            return json({ status: "success", data: { groups } });
+        }
+        if (base === undefined || (route !== base && !route.startsWith(`${base}/`)))
+            return notFound("404 page not found");
+        const parts = route.slice(base.length).split("/").filter(Boolean).map(decodeURIComponent);
+        if (req.method === "GET") {
+            if (parts.length === 0) {
+                const nonEmpty = Object.fromEntries(Object.entries(state.namespaces).filter(([, gs]) => gs.length > 0));
+                return Object.keys(nonEmpty).length === 0 ? notFound("no rule groups found") : ok(yaml(nonEmpty));
+            }
+            const groups = state.namespaces[parts[0]];
+            if (!groups || groups.length === 0)
+                return notFound("no rule groups found");
+            if (parts.length === 1)
+                return ok(yaml({ [parts[0]]: groups }));
+            const g = groups.find((x) => x.name === parts[1]);
+            return g ? ok(yaml(g)) : notFound("group does not exist");
+        }
+        if (req.method === "POST" && parts.length === 1) {
+            const doc = loadPrometheusYaml(req.body ?? "");
+            const groups = ((_a = state.namespaces)[_b = parts[0]] ?? (_a[_b] = []));
+            const i = groups.findIndex((x) => x.name === doc.name);
+            if (i >= 0)
+                groups[i] = doc;
+            else
+                groups.push(doc);
+            return { status: 202, text: "" };
+        }
+        if (req.method === "DELETE" && parts.length === 2) {
+            const groups = state.namespaces[parts[0]];
+            const i = groups ? groups.findIndex((x) => x.name === parts[1]) : -1;
+            if (i < 0)
+                return notFound("group does not exist");
+            groups.splice(i, 1);
+            return { status: 202, text: "" };
+        }
+        return { status: 405, text: "method not allowed" };
+    };
+}
+/** An Alertmanager over `state`: a plain one's `/api/v2/status`, or Mimir's and Cortex's `/api/v1/alerts` and per-tenant status. */
+export function fakeAlertmanager(state, calls = []) {
+    const statusPath = state.kind === "alertmanager" ? "/api/v2/status" : "/alertmanager/api/v2/status";
+    return (req) => {
+        calls.push(`${req.method} ${req.path}`);
+        if (state.status !== undefined)
+            return { status: state.status, text: "refused" };
+        const refused = tenantRefused(state.tenant, req);
+        if (refused)
+            return refused;
+        if (req.path === statusPath && req.method === "GET") {
+            const original = state.kind === "alertmanager" ? state.original : state.uploaded?.alertmanager_config;
+            if (original === undefined)
+                return notFound("the Alertmanager is not configured");
+            return json({
+                cluster: { name: "01FAKE", peers: [{ address: "10.0.0.1:9094", name: "01FAKE" }], status: state.cluster ?? "ready" },
+                config: { original },
+                uptime: "2026-10-06T08:00:00.000Z",
+                versionInfo: { branch: "HEAD", buildDate: "20260101-00:00:00", buildUser: "root@fake", goVersion: "go1.25", revision: "fake", version: state.version ?? "0.34.1" },
+            });
+        }
+        if (req.path === "/api/v1/alerts" && state.kind !== "alertmanager") {
+            if (req.method === "GET") {
+                if (!state.uploaded)
+                    return notFound("alertmanager storage object not found");
+                return ok(yaml({ template_files: state.uploaded.template_files ?? {}, alertmanager_config: state.uploaded.alertmanager_config }));
+            }
+            if (req.method === "POST") {
+                const doc = loadPrometheusYaml(req.body ?? "");
+                state.uploaded = { alertmanager_config: doc.alertmanager_config, template_files: doc.template_files ?? {} };
+                return { status: 201, text: "" };
+            }
+        }
+        return notFound("404 page not found");
+    };
+}
+/** A handler as a {@link PromHttp}, with no headers (a tenant-checking fake then refuses; use {@link serveFake} for those). */
+export function fakeHttp(handler, headers = {}) {
+    return async (method, path, body) => {
+        const res = handler({ method, path, headers, body: body?.text });
+        return { status: res.status, text: res.text };
+    };
+}
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        let data = "";
+        req.setEncoding("utf8");
+        req.on("data", (c) => (data += c));
+        req.on("end", () => resolve(data));
+        req.on("error", reject);
+    });
+}
+/** A handler behind a real HTTP server on 127.0.0.1, on a free port. `close()` stops it. */
+export async function serveFake(handler) {
+    const server = createServer(async (req, res) => {
+        const body = await readBody(req);
+        const headers = Object.fromEntries(Object.entries(req.headers).map(([k, v]) => [k, Array.isArray(v) ? v.join(",") : v]));
+        const out = handler({ method: req.method ?? "GET", path: req.url ?? "/", headers, ...(body ? { body } : {}) });
+        res.writeHead(out.status, { "content-type": out.contentType ?? "text/plain" });
+        res.end(out.text);
+    });
+    await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+    const { port } = server.address();
+    return {
+        url: `http://127.0.0.1:${port}`,
+        close: () => new Promise((resolve, reject) => server.close((err) => (err ? reject(err) : resolve()))),
+    };
+}

package/dist/api/index.js

@@ -0,0 +1,17 @@
+/**
+ * The ruler and Alertmanager API clients (#3371), as
+ * `@intentius/chant-lexicon-prometheus/api`.
+ *
+ * One transport for observe, live export and the ruler apply target
+ * (#3372): bind with {@link bindEndpoints} (or {@link bindRuler} /
+ * {@link bindAlertmanager}), then read and write through {@link RulerApi}
+ * and {@link AlertmanagerApi}. The ownership boundary is
+ * {@link declaredNamespaces}: nothing outside it is read for import, and an
+ * apply must not write or delete outside it.
+ */
+export { PromApiError, PromClient, promHttp, statusVerdict } from "./client.js";
+export { RulerApi } from "./ruler.js";
+export { AlertmanagerApi } from "./alertmanager.js";
+export { evaluatedToRuleGroup, groupHealth } from "./evaluated.js";
+export { bindAlertmanager, bindEndpoints, bindRuler, classifyPromFailure, PromBindingError } from "./bind.js";
+export { ALERTMANAGER_KINDS, RULER_KINDS, declaredNamespaces, namespaceOfGroup, resolveAlertmanagerTarget, resolveRulerTarget, } from "../config.js";

package/dist/api/ruler.js

@@ -0,0 +1,122 @@
+/**
+ * The ruler APIs (#3371): Mimir's, Cortex's and Loki's rule group config
+ * API, and the Prometheus-compatible `/api/v1/rules` every one of them (and
+ * a plain Prometheus) serves with each group's evaluation state.
+ *
+ * | Kind | Config API (YAML) | Evaluated rules (JSON) |
+ * |---|---|---|
+ * | `mimir` | `<prefix>/config/v1/rules[/{namespace}[/{group}]]` | `<prefix>/api/v1/rules` |
+ * | `cortex` | `/api/v1/rules[/{namespace}[/{group}]]` | `<prefix>/api/v1/rules` |
+ * | `loki` | `/loki/api/v1/rules[/{namespace}[/{group}]]` | `/prometheus/api/v1/rules` |
+ * | `prometheus` | none: rule files on disk | `/api/v1/rules` |
+ *
+ * `<prefix>` is `-http.prometheus-http-prefix`, `/prometheus` unless the
+ * profile says otherwise. Mimir does not register Cortex's `/api/v1/rules`
+ * config path. Every request carries the target's `X-Scope-OrgID`.
+ *
+ * The writes (`setGroup`, `deleteGroup`) are here for the ruler apply
+ * target (#3372), which reuses this module through
+ * `@intentius/chant-lexicon-prometheus/api`. Nothing here deletes a
+ * namespace: an apply bounded by the declared namespaces deletes groups one
+ * by one, and only inside {@link declaredNamespaces}.
+ */
+import { emitYaml } from "../build.js";
+import { loadPrometheusYaml } from "../import/parser.js";
+import { PromApiError } from "./client.js";
+function isObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+const enc = encodeURIComponent;
+/** A bound ruler: the transport and the target it reaches. */
+export class RulerApi {
+    constructor(client, target) {
+        this.client = client;
+        this.target = target;
+    }
+    /** The base of the rule group config API, or undefined for a plain Prometheus, which has none. */
+    get configPath() {
+        switch (this.target.kind) {
+            case "mimir":
+                return `${this.target.prometheusPrefix}/config/v1/rules`;
+            case "cortex":
+                return "/api/v1/rules";
+            case "loki":
+                return "/loki/api/v1/rules";
+            case "prometheus":
+                return undefined;
+        }
+    }
+    /** The Prometheus-compatible rules endpoint, with evaluation state. */
+    get evaluatedPath() {
+        return `${this.target.prometheusPrefix}/api/v1/rules`;
+    }
+    requireConfigPath() {
+        const p = this.configPath;
+        if (p === undefined)
+            throw new Error(`a plain Prometheus (${this.target.source}) has no rule group API; its groups come from rule files`);
+        return p;
+    }
+    parseNamespaces(text, path) {
+        const doc = loadPrometheusYaml(text);
+        if (!isObject(doc))
+            throw new PromApiError(502, "GET", path, "the answer is not a YAML mapping of namespaces to rule groups");
+        const out = {};
+        for (const [ns, groups] of Object.entries(doc)) {
+            out[ns] = (Array.isArray(groups) ? groups : []).filter((g) => isObject(g) && typeof g.name === "string");
+        }
+        return out;
+    }
+    /** Every namespace the tenant has, with its groups. A 404 (Mimir: "no rule groups found") is none. */
+    async listNamespaces() {
+        const path = this.requireConfigPath();
+        const text = await this.client.getText(path);
+        return text === undefined ? {} : this.parseNamespaces(text, path);
+    }
+    /** One namespace's groups; undefined when the ruler has no such namespace. */
+    async readNamespace(namespace) {
+        const path = `${this.requireConfigPath()}/${enc(namespace)}`;
+        const text = await this.client.getText(path);
+        if (text === undefined)
+            return undefined;
+        return this.parseNamespaces(text, path)[namespace] ?? [];
+    }
+    /** The path {@link readGroup} reads, for `queried`. */
+    groupPath(namespace, group) {
+        return `${this.requireConfigPath()}/${enc(namespace)}/${enc(group)}`;
+    }
+    /** One group; undefined when it is not there. */
+    async readGroup(namespace, group) {
+        const path = this.groupPath(namespace, group);
+        const text = await this.client.getText(path);
+        if (text === undefined)
+            return undefined;
+        const doc = loadPrometheusYaml(text);
+        if (!isObject(doc) || typeof doc.name !== "string")
+            throw new PromApiError(502, "GET", path, "the answer is not a rule group");
+        return doc;
+    }
+    /** Create or replace one group in `namespace` (202 on Mimir, Cortex and Loki). */
+    async setGroup(namespace, group) {
+        await this.client.send("POST", `${this.requireConfigPath()}/${enc(namespace)}`, { text: emitYaml(group), contentType: "application/yaml" });
+    }
+    /** Delete one group from `namespace`. */
+    async deleteGroup(namespace, group) {
+        await this.client.send("DELETE", this.groupPath(namespace, group));
+    }
+    /** Every group the ruler evaluates, with its health. Read once per client. */
+    async evaluated() {
+        return this.client.once("evaluated", async () => {
+            const path = this.evaluatedPath;
+            const body = await this.client.getJson(path);
+            if (body === undefined)
+                throw new PromApiError(404, "GET", path, "the rules API is not served here");
+            if (body.status !== undefined && body.status !== "success")
+                throw new PromApiError(502, "GET", path, `status ${body.status}`);
+            return (body.data?.groups ?? []).filter((g) => isObject(g) && typeof g.name === "string").map((g) => ({
+                ...g,
+                file: typeof g.file === "string" ? g.file : "",
+                rules: Array.isArray(g.rules) ? g.rules.filter(isObject) : [],
+            }));
+        });
+    }
+}

package/dist/build.js

@@ -0,0 +1,240 @@
+/**
+ * Declared entities -> `RuleFileConfig` / `AlertmanagerConfig` -> YAML.
+ *
+ * The serializer runs these over a build's entities, and a composite in
+ * another lexicon (the k8s `PrometheusRule` path, a ConfigMap holding
+ * `alertmanager.yml`) runs them over the entities it has. Both get the same
+ * config and the same text.
+ */
+import { dump } from "js-yaml";
+import { isAlertmanagerSettings, isInhibitRule, isReceiver, isRoute, isTimeInterval, } from "./alertmanager.js";
+import { isRuleGroup, ruleGroupConfig } from "./rules.js";
+import { isPrometheusConfig, isScrapeConfig, } from "./prometheus-config.js";
+import { PROMETHEUS_CONFIG_SECTIONS } from "./model.js";
+function byName(a, b) {
+    return String(a ?? "").localeCompare(String(b ?? ""));
+}
+function entityList(entities) {
+    return entities instanceof Map ? [...entities.values()] : [...entities];
+}
+/** A value with `undefined` keys dropped and entities left as they are. */
+function plain(value) {
+    if (value === undefined)
+        return undefined;
+    if (Array.isArray(value))
+        return value.map(plain);
+    if (typeof value === "object" && value !== null) {
+        const toJSON = value.toJSON;
+        if (typeof toJSON === "function")
+            return plain(toJSON.call(value));
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            if (v !== undefined)
+                out[k] = plain(v);
+        }
+        return out;
+    }
+    return value;
+}
+/** The rule file for a set of declared entities. Entities that aren't `RuleGroup`s are ignored. */
+export function buildRuleFile(entities) {
+    const groups = [];
+    for (const e of entityList(entities)) {
+        if (isRuleGroup(e) && !groups.includes(e))
+            groups.push(e);
+    }
+    // Sorted by name: Prometheus evaluates groups independently, so their order
+    // carries no meaning, and sorting makes the file the same however the
+    // groups were collected (a build's entity map, or a list passed by hand).
+    groups.sort((a, b) => byName(a.props.name, b.props.name));
+    return { config: { groups: groups.map((g) => ruleGroupConfig(g)) }, groups };
+}
+function receiverName(ref) {
+    return isReceiver(ref) ? ref.props.name : String(ref);
+}
+function intervalName(ref) {
+    return isTimeInterval(ref) ? ref.props.name : String(ref);
+}
+function routeProps(route) {
+    return isRoute(route) ? route.props : route;
+}
+function routeConfig(route) {
+    const p = routeProps(route);
+    const out = {};
+    if (p.receiver !== undefined)
+        out.receiver = receiverName(p.receiver);
+    if (p.group_by !== undefined)
+        out.group_by = [...p.group_by];
+    if (p.continue !== undefined)
+        out.continue = p.continue;
+    if (p.matchers !== undefined)
+        out.matchers = [...p.matchers];
+    if (p.group_wait !== undefined)
+        out.group_wait = p.group_wait;
+    if (p.group_interval !== undefined)
+        out.group_interval = p.group_interval;
+    if (p.repeat_interval !== undefined)
+        out.repeat_interval = p.repeat_interval;
+    if (p.mute_time_intervals !== undefined)
+        out.mute_time_intervals = p.mute_time_intervals.map(intervalName);
+    if (p.active_time_intervals !== undefined)
+        out.active_time_intervals = p.active_time_intervals.map(intervalName);
+    if (p.labels !== undefined)
+        out.labels = { ...p.labels };
+    if (p.routes !== undefined)
+        out.routes = p.routes.map(routeConfig);
+    return out;
+}
+/** The `alertmanager.yml` for a set of declared entities. Entities that aren't Alertmanager ones are ignored. */
+export function buildAlertmanagerConfig(entities) {
+    const all = entityList(entities);
+    const warnings = [];
+    const receivers = [];
+    const intervals = [];
+    const routes = [];
+    const inhibits = [];
+    let settings;
+    let count = 0;
+    const addReceiver = (r) => {
+        if (!receivers.includes(r))
+            receivers.push(r);
+    };
+    const addInterval = (t) => {
+        if (!intervals.includes(t))
+            intervals.push(t);
+    };
+    for (const e of all) {
+        if (isReceiver(e))
+            addReceiver(e);
+        else if (isTimeInterval(e))
+            addInterval(e);
+        else if (isRoute(e))
+            routes.push(e);
+        else if (isInhibitRule(e))
+            inhibits.push(plain(e.props));
+        else if (isAlertmanagerSettings(e)) {
+            if (settings)
+                warnings.push("prometheus: more than one AlertmanagerSettings is declared; the first one is used");
+            else
+                settings = e;
+        }
+        else
+            continue;
+        count++;
+    }
+    // Receivers and time intervals a route references by entity are part of the
+    // config even when not declared on their own, and child Route entities are
+    // not roots.
+    const children = new Set();
+    const walk = (route) => {
+        const p = routeProps(route);
+        if (isReceiver(p.receiver))
+            addReceiver(p.receiver);
+        for (const t of [...(p.mute_time_intervals ?? []), ...(p.active_time_intervals ?? [])]) {
+            if (isTimeInterval(t))
+                addInterval(t);
+        }
+        for (const child of p.routes ?? []) {
+            if (isRoute(child))
+                children.add(child);
+            walk(child);
+        }
+    };
+    for (const r of routes)
+        walk(r);
+    const roots = routes.filter((r) => !children.has(r));
+    if (roots.length > 1) {
+        warnings.push(`prometheus: ${roots.length} root Routes are declared; Alertmanager has one routing tree, so the first is used. Nest the others under its routes.`);
+    }
+    const config = {};
+    if (settings?.props.global)
+        config.global = plain(settings.props.global);
+    if (settings?.props.templates)
+        config.templates = [...settings.props.templates];
+    if (roots.length > 0)
+        config.route = routeConfig(roots[0]);
+    if (inhibits.length > 0)
+        config.inhibit_rules = inhibits;
+    // Receivers and time intervals are looked up by name, so their order carries
+    // no meaning; sorted, the file is the same however they were collected.
+    receivers.sort((a, b) => byName(a.props.name, b.props.name));
+    intervals.sort((a, b) => byName(a.props.name, b.props.name));
+    if (receivers.length > 0)
+        config.receivers = receivers.map((r) => plain(r.props));
+    if (intervals.length > 0)
+        config.time_intervals = intervals.map((t) => plain(t.props));
+    if (settings?.props.tracing)
+        config.tracing = plain(settings.props.tracing);
+    return { config, warnings, count };
+}
+/**
+ * The `prometheus.yml` for a set of declared entities. Entities that aren't
+ * `PrometheusConfig`s or `ScrapeConfig`s are ignored. Sections come out in the
+ * order Prometheus documents them, and scrape jobs are sorted by name: the
+ * jobs are independent, so their order carries no meaning.
+ */
+export function buildPrometheusConfig(entities) {
+    const warnings = [];
+    const jobs = [];
+    const seen = new Set();
+    let main;
+    let count = 0;
+    const addJob = (job) => {
+        if (seen.has(job))
+            return;
+        seen.add(job);
+        jobs.push(plain(isScrapeConfig(job) ? job.props : job));
+    };
+    for (const e of entityList(entities)) {
+        if (isScrapeConfig(e)) {
+            addJob(e);
+            count++;
+        }
+        else if (isPrometheusConfig(e)) {
+            if (main)
+                warnings.push("prometheus: more than one PrometheusConfig is declared; the first one is used");
+            else
+                main = e;
+            count++;
+        }
+    }
+    for (const job of main?.props.scrape_configs ?? [])
+        addJob(job);
+    const names = new Map();
+    for (const j of jobs)
+        names.set(j.job_name, (names.get(j.job_name) ?? 0) + 1);
+    for (const [name, n] of names) {
+        if (n > 1)
+            warnings.push(`prometheus: ${n} scrape configs are named "${name}"; Prometheus rejects a file with a repeated job_name`);
+    }
+    jobs.sort((a, b) => byName(a.job_name, b.job_name));
+    const sections = (plain(main?.props ?? {}) ?? {});
+    const config = {};
+    for (const key of PROMETHEUS_CONFIG_SECTIONS) {
+        if (key === "scrape_configs") {
+            if (jobs.length > 0)
+                config.scrape_configs = jobs;
+        }
+        else if (sections[key] !== undefined) {
+            config[key] = sections[key];
+        }
+    }
+    return { config: config, warnings, count };
+}
+// ── YAML ────────────────────────────────────────────────────────────
+/** Print a rule file or Alertmanager config as YAML, keys in the order given. */
+export function emitYaml(value) {
+    return dump(value, { lineWidth: -1, noRefs: true, quotingType: '"', sortKeys: false });
+}
+/** The rule file YAML for a set of declared entities, exactly as the serializer emits it. */
+export function ruleFileYaml(entities) {
+    return emitYaml(buildRuleFile(entities).config);
+}
+/** The `alertmanager.yml` text for a set of declared entities, exactly as the serializer emits it. */
+export function alertmanagerYaml(entities) {
+    return emitYaml(buildAlertmanagerConfig(entities).config);
+}
+/** The `prometheus.yml` text for a set of declared entities, exactly as the serializer emits it. */
+export function prometheusConfigYaml(entities) {
+    return emitYaml(buildPrometheusConfig(entities).config);
+}