@intentius/chant-lexicon-prometheus 0.124.31 → 0.124.33

package/dist/rule-eval.js

@@ -0,0 +1,466 @@
+/**
+ * A small rule-file evaluator, for tests over synthetic series.
+ *
+ * It evaluates recording and alerting rules the way Prometheus does, one
+ * evaluation step at a time: each group's rules in order, recording rule
+ * results written back as series the later rules (and later steps) read.
+ * The PromQL it understands is the subset the lexicon's generated rules use:
+ * number literals, vector and range selectors with `=`, `!=`, `=~` and `!~`
+ * matchers, `rate`, `increase`, `avg_over_time`, `sum_over_time`,
+ * `count_over_time`, `vector`, `histogram_quantile`, `sum` (with `by` or
+ * `without`), the arithmetic and comparison operators (one-to-one, or
+ * many-to-one with `group_left` and no extra labels) and `and`, `or` and
+ * `unless` (with `on` or `ignoring`). Anything else throws, so a test never
+ * passes by silently evaluating something it does not understand.
+ *
+ * `histogram_quantile` interpolates linearly inside the bucket the rank
+ * falls in, as Prometheus does for classic buckets, and returns the upper
+ * bound of the highest finite bucket when the rank falls in `+Inf`.
+ *
+ * `rate` is the increase between the first and last sample in the range
+ * over the time between them, without Prometheus's extrapolation to the
+ * range's edges. For two counters sampled together that changes neither's
+ * ratio, which is what an SLI is. `promtool test rules`, when installed,
+ * checks the same rules with Prometheus's own engine.
+ *
+ * Not exported from the package root; tests import it by path.
+ */
+import { parser } from "@prometheus-io/lezer-promql";
+import { durationMs } from "./duration.js";
+import { isAlertingRuleConfig, isRecordingRuleConfig } from "./model.js";
+const LOOKBACK_MS = 5 * 60000;
+const RANGE_FUNCTIONS = new Set(["rate", "increase", "avg_over_time", "sum_over_time", "count_over_time"]);
+function key(labels) {
+    return JSON.stringify(Object.entries(labels).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+}
+function withoutName(labels) {
+    const { __name__: _, ...rest } = labels;
+    return rest;
+}
+function matches(labels, m) {
+    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);
+    }
+}
+/** An in-memory series store with rule evaluation over it. */
+export class RuleEvaluator {
+    constructor(groups) {
+        this.groups = groups;
+        this.series = new Map();
+        /** When each active alert started, per alerting rule. */
+        this.pending = new Map();
+    }
+    /** Append one sample; samples of a series must arrive in time order. */
+    add(labels, t, v) {
+        const k = key(labels);
+        let s = this.series.get(k);
+        if (!s) {
+            s = { labels: { ...labels }, samples: [] };
+            this.series.set(k, s);
+        }
+        s.samples.push({ t, v });
+    }
+    /** Evaluate every group at time `t` (milliseconds); returns the alerts firing at `t`. */
+    step(t) {
+        const firing = [];
+        for (const group of this.groups) {
+            const groupLabels = group.labels ?? {};
+            for (const rule of group.rules) {
+                const result = this.eval(rule.expr, t);
+                const elements = result.kind === "scalar" ? [{ labels: {}, value: result.value }] : result.elements;
+                if (isRecordingRuleConfig(rule)) {
+                    for (const e of elements) {
+                        if (Number.isNaN(e.value))
+                            continue;
+                        this.add({ ...withoutName(e.labels), ...groupLabels, ...(rule.labels ?? {}), __name__: rule.record }, t, e.value);
+                    }
+                }
+                else if (isAlertingRuleConfig(rule)) {
+                    const before = this.pending.get(rule) ?? new Map();
+                    const now = new Map();
+                    const holdMs = rule.for ? (durationMs(rule.for) ?? 0) : 0;
+                    for (const e of elements) {
+                        const labels = { ...withoutName(e.labels), ...groupLabels, ...(rule.labels ?? {}), alertname: rule.alert };
+                        const k = key(labels);
+                        const since = before.get(k) ?? t;
+                        now.set(k, since);
+                        if (t - since >= holdMs)
+                            firing.push({ labels, value: e.value });
+                    }
+                    this.pending.set(rule, now);
+                }
+            }
+        }
+        return firing;
+    }
+    /** The latest value of each series matching `selector` at `t`, e.g. `slo:x{slo="a"}`. */
+    query(expr, t) {
+        const v = this.eval(expr, t);
+        return v.kind === "scalar" ? [{ labels: {}, value: v.value }] : v.elements;
+    }
+    eval(expr, t) {
+        const tree = parser.parse(expr);
+        const top = tree.topNode.firstChild;
+        if (!top)
+            throw new Error(`rule-eval: empty expression`);
+        return this.node(top, expr, t);
+    }
+    text(n, src) {
+        return src.slice(n.from, n.to);
+    }
+    matchers(sel, src) {
+        const out = [];
+        const ident = sel.getChild("Identifier");
+        if (ident)
+            out.push({ name: "__name__", op: "=", value: this.text(ident, src) });
+        const list = sel.getChild("LabelMatchers");
+        if (list) {
+            for (let c = list.firstChild; c; c = c.nextSibling) {
+                if (c.name !== "UnquotedLabelMatcher")
+                    continue;
+                const name = this.text(c.getChild("LabelName"), src);
+                const op = this.text(c.getChild("MatchOp"), src);
+                const value = JSON.parse(this.text(c.getChild("StringLiteral"), src).replace(/^'|'$/g, '"'));
+                out.push({ name, op, value });
+            }
+        }
+        return out;
+    }
+    select(ms) {
+        return [...this.series.values()].filter((s) => ms.every((m) => matches(s.labels, m)));
+    }
+    /** Samples in (t - range, t]. */
+    window(s, t, rangeMs) {
+        const xs = s.samples;
+        let lo = 0;
+        let hi = xs.length;
+        while (lo < hi) {
+            const mid = (lo + hi) >> 1;
+            if (xs[mid].t <= t - rangeMs)
+                lo = mid + 1;
+            else
+                hi = mid;
+        }
+        const out = [];
+        for (let i = lo; i < xs.length && xs[i].t <= t; i++)
+            out.push(xs[i]);
+        return out;
+    }
+    node(n, src, t) {
+        switch (n.name) {
+            case "NumberDurationLiteral":
+                return { kind: "scalar", value: Number(this.text(n, src)) };
+            case "ParenExpr":
+                return this.node(n.firstChild, src, t);
+            case "VectorSelector": {
+                const elements = [];
+                for (const s of this.select(this.matchers(n, src))) {
+                    const w = this.window(s, t, LOOKBACK_MS);
+                    if (w.length > 0)
+                        elements.push({ labels: { ...s.labels }, value: w[w.length - 1].v });
+                }
+                return { kind: "vector", elements };
+            }
+            case "FunctionCall":
+                return this.call(n, src, t);
+            case "AggregateExpr":
+                return this.aggregate(n, src, t);
+            case "BinaryExpr":
+                return this.binary(n, src, t);
+            default:
+                throw new Error(`rule-eval: ${n.name} (${this.text(n, src)}) is not supported`);
+        }
+    }
+    args(body) {
+        const out = [];
+        for (let c = body.firstChild; c; c = c.nextSibling) {
+            if (c.name !== "(" && c.name !== ")" && c.name !== ",")
+                out.push(c);
+        }
+        return out;
+    }
+    call(n, src, t) {
+        const fn = this.text(n.getChild("FunctionIdentifier"), src);
+        const [arg, second] = this.args(n.getChild("FunctionCallBody"));
+        if (fn === "histogram_quantile")
+            return this.histogramQuantile(arg, second, src, t);
+        if (fn === "vector") {
+            const v = this.node(arg, src, t);
+            if (v.kind !== "scalar")
+                throw new Error("rule-eval: vector() takes a scalar");
+            return { kind: "vector", elements: [{ labels: {}, value: v.value }] };
+        }
+        // Checked before any series is read, so an unsupported function throws even over no data.
+        if (!RANGE_FUNCTIONS.has(fn))
+            throw new Error(`rule-eval: function ${fn} is not supported`);
+        if (arg.name !== "MatrixSelector")
+            throw new Error(`rule-eval: ${fn}() needs a range selector`);
+        const rangeMs = durationMs(this.text(arg.getChild("DurationExpr"), src));
+        if (rangeMs === undefined)
+            throw new Error(`rule-eval: bad range in ${this.text(arg, src)}`);
+        const elements = [];
+        for (const s of this.select(this.matchers(arg.getChild("VectorSelector"), src))) {
+            const w = this.window(s, t, rangeMs);
+            let value;
+            switch (fn) {
+                case "rate":
+                case "increase": {
+                    if (w.length < 2)
+                        continue;
+                    const inc = w[w.length - 1].v - w[0].v;
+                    value = fn === "rate" ? inc / ((w[w.length - 1].t - w[0].t) / 1000) : (inc * rangeMs) / (w[w.length - 1].t - w[0].t);
+                    break;
+                }
+                case "avg_over_time":
+                case "sum_over_time":
+                case "count_over_time": {
+                    if (w.length === 0)
+                        continue;
+                    const sum = w.reduce((a, x) => a + x.v, 0);
+                    value = fn === "sum_over_time" ? sum : fn === "count_over_time" ? w.length : sum / w.length;
+                    break;
+                }
+                default:
+                    throw new Error(`rule-eval: function ${fn} is not supported`);
+            }
+            elements.push({ labels: withoutName(s.labels), value });
+        }
+        return { kind: "vector", elements };
+    }
+    histogramQuantile(qNode, vNode, src, t) {
+        const q = this.node(qNode, src, t);
+        const v = this.node(vNode, src, t);
+        if (q.kind !== "scalar" || v.kind !== "vector")
+            throw new Error("rule-eval: histogram_quantile takes a scalar and a vector");
+        const groups = new Map();
+        for (const e of v.elements) {
+            const { le, ...rest } = withoutName(e.labels);
+            if (le === undefined)
+                continue;
+            const k = key(rest);
+            const g = groups.get(k) ?? { labels: rest, buckets: [] };
+            g.buckets.push({ le: le === "+Inf" ? Infinity : Number(le), count: e.value });
+            groups.set(k, g);
+        }
+        const elements = [];
+        for (const { labels, buckets } of groups.values()) {
+            buckets.sort((a, b) => a.le - b.le);
+            const last = buckets[buckets.length - 1];
+            if (!last || last.le !== Infinity)
+                continue;
+            const total = last.count;
+            let value;
+            if (q.value < 0)
+                value = -Infinity;
+            else if (q.value > 1)
+                value = Infinity;
+            else if (!(total > 0))
+                value = NaN;
+            else {
+                const rank = q.value * total;
+                const i = buckets.findIndex((b) => b.count >= rank);
+                if (buckets[i].le === Infinity)
+                    value = buckets.length > 1 ? buckets[buckets.length - 2].le : NaN;
+                else {
+                    const start = i === 0 ? 0 : buckets[i - 1].le;
+                    const below = i === 0 ? 0 : buckets[i - 1].count;
+                    const inBucket = buckets[i].count - below;
+                    value = inBucket > 0 ? start + (buckets[i].le - start) * ((rank - below) / inBucket) : buckets[i].le;
+                }
+            }
+            elements.push({ labels, value });
+        }
+        return { kind: "vector", elements };
+    }
+    aggregate(n, src, t) {
+        const op = this.text(n.getChild("AggregateOp"), src);
+        if (op !== "sum")
+            throw new Error(`rule-eval: aggregation ${op} is not supported`);
+        const mod = n.getChild("AggregateModifier");
+        let by;
+        let without;
+        if (mod) {
+            const names = (mod.getChild("GroupingLabels")?.getChildren("LabelName") ?? []).map((l) => this.text(l, src));
+            if (mod.getChild("By"))
+                by = names;
+            else
+                without = names;
+        }
+        const [arg] = this.args(n.getChild("FunctionCallBody"));
+        const v = this.node(arg, src, t);
+        if (v.kind !== "vector")
+            throw new Error("rule-eval: sum() takes a vector");
+        const groups = new Map();
+        for (const e of v.elements) {
+            const base = withoutName(e.labels);
+            const labels = {};
+            if (by)
+                for (const l of by)
+                    if (base[l] !== undefined)
+                        labels[l] = base[l];
+            if (without)
+                for (const [k, val] of Object.entries(base))
+                    if (!without.includes(k))
+                        labels[k] = val;
+            const k = key(labels);
+            const g = groups.get(k);
+            if (g)
+                g.value += e.value;
+            else
+                groups.set(k, { labels, value: e.value });
+        }
+        return { kind: "vector", elements: [...groups.values()] };
+    }
+    binary(n, src, t) {
+        const parts = [];
+        for (let c = n.firstChild; c; c = c.nextSibling)
+            parts.push(c);
+        const lhsNode = parts[0];
+        const rhsNode = parts[parts.length - 1];
+        const opNode = parts[1];
+        const op = this.text(opNode, src);
+        const modifier = parts.find((p) => p.name === "MatchingModifierClause");
+        if (parts.some((p) => p.name === "BoolModifier"))
+            throw new Error("rule-eval: bool modifier is not supported");
+        let on;
+        let ignoring = [];
+        let groupLeft = false;
+        if (modifier) {
+            const grouping = modifier.getChild("GroupingLabels");
+            const names = (grouping?.getChildren("LabelName") ?? []).map((l) => this.text(l, src));
+            if (modifier.getChild("On"))
+                on = names;
+            else
+                ignoring = names;
+            if (modifier.getChild("GroupRight"))
+                throw new Error("rule-eval: group_right is not supported");
+            const left = modifier.getChild("GroupLeft");
+            if (left) {
+                // group_left(<labels>) copies labels from the one side; only the bare form is supported.
+                const after = left.nextSibling;
+                if (after && after.name === "GroupingLabels" && after !== grouping)
+                    throw new Error("rule-eval: group_left with labels is not supported");
+                groupLeft = true;
+            }
+        }
+        const lhs = this.node(lhsNode, src, t);
+        const rhs = this.node(rhsNode, src, t);
+        const signature = (labels) => {
+            const base = withoutName(labels);
+            const picked = {};
+            for (const [k, v] of Object.entries(base)) {
+                if (on ? on.includes(k) : !ignoring.includes(k))
+                    picked[k] = v;
+            }
+            return key(picked);
+        };
+        if (op === "and" || op === "or" || op === "unless") {
+            if (lhs.kind !== "vector" || rhs.kind !== "vector")
+                throw new Error(`rule-eval: ${op} takes two vectors`);
+            const rhsSigs = new Set(rhs.elements.map((e) => signature(e.labels)));
+            if (op === "and")
+                return { kind: "vector", elements: lhs.elements.filter((e) => rhsSigs.has(signature(e.labels))) };
+            if (op === "unless")
+                return { kind: "vector", elements: lhs.elements.filter((e) => !rhsSigs.has(signature(e.labels))) };
+            const lhsSigs = new Set(lhs.elements.map((e) => signature(e.labels)));
+            return { kind: "vector", elements: [...lhs.elements, ...rhs.elements.filter((e) => !lhsSigs.has(signature(e.labels)))] };
+        }
+        const comparison = [">", "<", ">=", "<=", "==", "!="].includes(op);
+        const apply = (a, b) => {
+            switch (op) {
+                case "+":
+                    return a + b;
+                case "-":
+                    return a - b;
+                case "*":
+                    return a * b;
+                case "/":
+                    return a / b;
+                case ">":
+                    return a > b ? a : undefined;
+                case "<":
+                    return a < b ? a : undefined;
+                case ">=":
+                    return a >= b ? a : undefined;
+                case "<=":
+                    return a <= b ? a : undefined;
+                case "==":
+                    return a === b ? a : undefined;
+                case "!=":
+                    return a !== b ? a : undefined;
+                default:
+                    throw new Error(`rule-eval: operator ${op} is not supported`);
+            }
+        };
+        if (lhs.kind === "scalar" && rhs.kind === "scalar") {
+            if (comparison)
+                throw new Error("rule-eval: scalar comparison needs bool");
+            return { kind: "scalar", value: apply(lhs.value, rhs.value) };
+        }
+        const keepName = comparison;
+        if (lhs.kind === "vector" && rhs.kind === "scalar") {
+            const elements = [];
+            for (const e of lhs.elements) {
+                const v = apply(e.value, rhs.value);
+                if (v !== undefined)
+                    elements.push({ labels: keepName ? e.labels : withoutName(e.labels), value: v });
+            }
+            return { kind: "vector", elements };
+        }
+        if (lhs.kind === "scalar" && rhs.kind === "vector") {
+            const elements = [];
+            for (const e of rhs.elements) {
+                const v = apply(lhs.value, e.value);
+                // A scalar-vector comparison filters the vector and keeps its sample value.
+                if (v !== undefined)
+                    elements.push({ labels: keepName ? e.labels : withoutName(e.labels), value: comparison ? e.value : v });
+            }
+            return { kind: "vector", elements };
+        }
+        const l = lhs;
+        const r = rhs;
+        const bySig = new Map();
+        for (const e of r.elements) {
+            const s = signature(e.labels);
+            if (bySig.has(s))
+                throw new Error("rule-eval: many-to-many matching is not supported");
+            bySig.set(s, e);
+        }
+        if (!groupLeft) {
+            const seen = new Set();
+            for (const e of l.elements) {
+                const s = signature(e.labels);
+                if (seen.has(s))
+                    throw new Error("rule-eval: many-to-one matching needs group_left");
+                seen.add(s);
+            }
+        }
+        const elements = [];
+        for (const e of l.elements) {
+            const other = bySig.get(signature(e.labels));
+            if (!other)
+                continue;
+            const v = apply(e.value, other.value);
+            if (v === undefined)
+                continue;
+            const labels = on && !keepName ? pick(withoutName(e.labels), on) : keepName ? e.labels : withoutName(e.labels);
+            elements.push({ labels, value: v });
+        }
+        return { kind: "vector", elements };
+    }
+}
+function pick(labels, names) {
+    const out = {};
+    for (const n of names)
+        if (labels[n] !== undefined)
+            out[n] = labels[n];
+    return out;
+}

package/dist/rules.js

@@ -0,0 +1,97 @@
+/**
+ * `RuleGroup`: one group of recording and alerting rules.
+ *
+ * A group is the unit Prometheus evaluates together, on one interval, and
+ * the unit both destinations take: an entry under `groups:` in a rule file,
+ * and an entry in a Prometheus Operator `PrometheusRule`'s `spec.groups`. The
+ * same declaration renders to either; `ruleGroupConfig()` is the one
+ * conversion both go through.
+ *
+ * Rules are plain objects in the rule file's own shape, so a composite (the
+ * SLO declaration, say) can build them as data and hand a list to one or
+ * more groups.
+ */
+import { createResource } from "@intentius/chant/runtime";
+import { isAlertingRuleConfig, isRecordingRuleConfig, } from "./model.js";
+export const RULE_GROUP_TYPE = "Prometheus::Rules::RuleGroup";
+const RuleGroupBase = createResource(RULE_GROUP_TYPE, "prometheus", {});
+/**
+ * A group of recording and alerting rules.
+ *
+ * @example
+ * ```ts
+ * export const api = new RuleGroup({
+ *   name: "api",
+ *   interval: "30s",
+ *   rules: [
+ *     { record: "job:http_requests:rate5m", expr: "sum by (job) (rate(http_requests_total[5m]))" },
+ *     {
+ *       alert: "ApiHighErrorRate",
+ *       expr: 'sum(rate(http_requests_total{code=~"5.."}[5m])) / sum(rate(http_requests_total[5m])) > 0.05',
+ *       for: "10m",
+ *       labels: { severity: "page" },
+ *       annotations: { summary: "API 5xx ratio above 5%" },
+ *     },
+ *   ],
+ * });
+ * ```
+ */
+export const RuleGroup = function (props) {
+    RuleGroupBase.call(this, props);
+    Object.defineProperty(this, "groupName", { value: props?.name, enumerable: false });
+};
+Object.defineProperty(RuleGroup, "name", { value: "RuleGroup" });
+/** True when `value` is a declared `RuleGroup`. */
+export function isRuleGroup(value) {
+    return typeof value === "object" && value !== null && value.entityType === RULE_GROUP_TYPE;
+}
+function labelSet(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+        if (v !== undefined)
+            out[k] = String(v);
+    }
+    return out;
+}
+function defined(obj) {
+    for (const k of Object.keys(obj))
+        if (obj[k] === undefined)
+            delete obj[k];
+    return obj;
+}
+/** A rule in canonical key order, `undefined` fields dropped. */
+export function ruleConfig(rule) {
+    if (isRecordingRuleConfig(rule)) {
+        return defined({ record: rule.record, expr: rule.expr, labels: labelSet(rule.labels) });
+    }
+    if (isAlertingRuleConfig(rule)) {
+        return defined({
+            alert: rule.alert,
+            expr: rule.expr,
+            for: rule.for,
+            keep_firing_for: rule.keep_firing_for,
+            labels: labelSet(rule.labels),
+            annotations: labelSet(rule.annotations),
+        });
+    }
+    // Neither `record` nor `alert`: keep it as written, and let PROM105 name it.
+    return { ...rule };
+}
+/**
+ * The plain group a `RuleGroup` (or group props) renders to, in canonical key
+ * order. This is what goes under `groups:` in a rule file and into a
+ * `PrometheusRule`'s `spec.groups`.
+ */
+export function ruleGroupConfig(group) {
+    const p = isRuleGroup(group) ? group.props : group;
+    return defined({
+        name: p.name,
+        interval: p.interval,
+        query_offset: p.query_offset,
+        limit: p.limit,
+        labels: labelSet(p.labels),
+        rules: (p.rules ?? []).map(ruleConfig),
+    });
+}

package/dist/serializer.js

@@ -0,0 +1,59 @@
+/**
+ * Prometheus serializer.
+ *
+ * Emits the files a Prometheus setup reads:
+ *
+ * - the rule file (`groups:`), from every `RuleGroup` in the build, the file
+ *   `rule_files:` points at and `promtool check rules` reads;
+ * - `prometheus.yml`, from the `PrometheusConfig` and `ScrapeConfig`
+ *   entities, the file `promtool check config` reads;
+ * - `alertmanager.yml`, from the `Route`, `Receiver`, `InhibitRule`,
+ *   `TimeInterval` and `AlertmanagerSettings` entities, the file
+ *   `amtool check-config` reads.
+ *
+ * The first of those a build produces, in that order, is the primary output
+ * and the others are written beside it: the rule file, then `prometheus.yml`
+ * (`PROMETHEUS_FILE`), then `alertmanager.yml`. A project that declares only
+ * rule groups, or only Alertmanager entities, sees no change. Rules inside a
+ * group and child routes keep the order they are written in, which is the
+ * order that matters to Prometheus and Alertmanager; groups, scrape jobs,
+ * receivers and time intervals, whose order means nothing, are sorted by name.
+ *
+ * None of these files has a metadata channel, so there is no ownership marker
+ * to stamp.
+ */
+import { buildAlertmanagerConfig, buildPrometheusConfig, buildRuleFile, emitYaml } from "./build.js";
+/** The filename `prometheus.yml` is written under when it sits beside a rule file or `alertmanager.yml`. */
+export const PROMETHEUS_FILE = "prometheus.yml";
+/** The filename `alertmanager.yml` is written under when it sits beside a rule file. */
+export const ALERTMANAGER_FILE = "alertmanager.yml";
+export const prometheusSerializer = {
+    name: "prometheus",
+    rulePrefix: "PROM",
+    serialize(entities, _outputs) {
+        const rules = buildRuleFile(entities);
+        const prom = buildPrometheusConfig(entities);
+        const am = buildAlertmanagerConfig(entities);
+        const warnings = [...prom.warnings, ...am.warnings];
+        // The files this build writes, in the order of the primary: the rule file,
+        // then prometheus.yml, then alertmanager.yml.
+        const out = [];
+        if (rules.groups.length > 0)
+            out.push(["rules", emitYaml(rules.config)]);
+        if (prom.count > 0)
+            out.push([PROMETHEUS_FILE, emitYaml(prom.config)]);
+        if (am.count > 0)
+            out.push([ALERTMANAGER_FILE, emitYaml(am.config)]);
+        if (out.length === 0)
+            return "";
+        if (out.length === 1) {
+            return warnings.length === 0 ? out[0][1] : { primary: out[0][1], warnings };
+        }
+        const [[, primary], ...rest] = out;
+        return {
+            primary,
+            files: Object.fromEntries(rest),
+            ...(warnings.length > 0 ? { warnings } : {}),
+        };
+    },
+};

package/dist/skill-defs.js

@@ -0,0 +1,41 @@
+import { createSkillsLoader } from "@intentius/chant/lexicon-plugin-helpers";
+/** The prometheus lexicon's AI skills, read from src/skills/. */
+export const prometheusSkills = createSkillsLoader(import.meta.url, [
+    {
+        file: "chant-prometheus.md",
+        name: "chant-prometheus",
+        description: "Declare Prometheus recording and alerting rule groups as typed chant entities and build a rule file that passes promtool",
+        triggers: [
+            { type: "context", value: "prometheus rules" },
+            { type: "context", value: "alerting rule" },
+            { type: "context", value: "recording rule" },
+        ],
+        examples: [
+            {
+                title: "A recording rule and an alert on it",
+                output: "export const api = new RuleGroup({\n" +
+                    '  name: "api",\n' +
+                    "  rules: [\n" +
+                    '    { record: "job:http_errors:ratio5m", expr: \'sum by (job) (rate(http_requests_total{code=~"5.."}[5m])) / sum by (job) (rate(http_requests_total[5m]))\' },\n' +
+                    '    { alert: "ApiErrors", expr: "job:http_errors:ratio5m > 0.05", for: "10m", labels: { severity: "page" }, annotations: { summary: "5xx ratio above 5%" } },\n' +
+                    "  ],\n" +
+                    "});",
+            },
+        ],
+    },
+    {
+        file: "chant-prometheus-alertmanager.md",
+        name: "chant-prometheus-alertmanager",
+        description: "Declare Alertmanager routing (routes, receivers, inhibit rules, time intervals) and keep every alert severity routed",
+        triggers: [
+            { type: "context", value: "alertmanager" },
+            { type: "context", value: "alert routing" },
+        ],
+    },
+    {
+        file: "chant-prometheus-kubernetes.md",
+        name: "chant-prometheus-kubernetes",
+        description: "Render the same RuleGroups into a Prometheus Operator PrometheusRule, or into ConfigMaps for a plain Prometheus and Alertmanager on Kubernetes",
+        triggers: [{ type: "context", value: "PrometheusRule" }],
+    },
+]);