@intentius/chant-lexicon-prometheus 0.124.31 → 0.124.32

package/dist/op/activities/silence.js

@@ -0,0 +1,123 @@
+/**
+ * Alertmanager silences as Op steps (#3369): silence the alerts a change is
+ * expected to set off, and expire the silence when the change is done or
+ * has failed.
+ *
+ * `alertmanagerSilence` creates a silence through `POST /api/v2/silences`
+ * and records its id in a file under the working directory
+ * (`.chant/alertmanager-silences/<record>.json`). Step-output references are
+ * not available in an Op's `onFailure` phases, so the record is how a final
+ * phase and an `onFailure` phase alike find the silence:
+ * `alertmanagerUnsilence({ record })` expires every silence the record
+ * holds through `DELETE /api/v2/silence/{id}`, and drops them from it. An
+ * already-expired or unknown silence counts as expired, so the step can
+ * run in both places.
+ *
+ * The Alertmanager is `url`, else `$ALERTMANAGER_URL`, else
+ * `http://localhost:9093`.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { currentOpRun } from "@intentius/chant/op";
+import { durationMs } from "../../duration.js";
+import { parseMatchers } from "../../matchers.js";
+export function alertmanagerUrl(url) {
+    return (url ?? process.env.ALERTMANAGER_URL ?? "http://localhost:9093").replace(/\/+$/, "");
+}
+/** The API matchers for `matchers`. */
+export function apiMatchers(matchers) {
+    if (!Array.isArray(matchers)) {
+        return Object.entries(matchers).map(([name, value]) => ({ name, value, isRegex: false, isEqual: true }));
+    }
+    const out = [];
+    for (const entry of matchers) {
+        const parsed = parseMatchers(entry);
+        if (!parsed.ok)
+            throw new Error(`matcher ${JSON.stringify(entry)}: ${parsed.error}`);
+        for (const m of parsed.matchers)
+            out.push({ name: m.name, value: m.value, isRegex: m.op.endsWith("~"), isEqual: !m.op.startsWith("!") });
+    }
+    if (out.length === 0)
+        throw new Error("a silence needs at least one matcher");
+    return out;
+}
+export function recordPath(record = "silence", recordDir = ".chant/alertmanager-silences", cwd = process.cwd()) {
+    if (!/^[A-Za-z0-9._-]+$/.test(record))
+        throw new Error(`record ${JSON.stringify(record)}: use letters, digits, dot, dash and underscore`);
+    return join(resolve(cwd, recordDir), `${record}.json`);
+}
+function readRecord(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        return Array.isArray(parsed.silences) ? parsed.silences : [];
+    }
+    catch {
+        return [];
+    }
+}
+function writeRecord(path, silences) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify({ silences }, null, 2)}\n`);
+}
+/** Create a silence and record its id. */
+export async function alertmanagerSilence(args) {
+    const f = args._fetch ?? fetch;
+    const url = alertmanagerUrl(args.url);
+    const ms = durationMs(args.duration);
+    if (!ms || ms <= 0)
+        throw new Error(`duration ${JSON.stringify(args.duration)} is not a Prometheus duration such as 30m`);
+    const run = currentOpRun();
+    const now = (args._now ?? (() => new Date()))();
+    const startsAt = now.toISOString();
+    const endsAt = new Date(now.getTime() + ms).toISOString();
+    const body = {
+        matchers: apiMatchers(args.matchers),
+        startsAt,
+        endsAt,
+        createdBy: args.createdBy ?? (run ? `chant op ${run.op}` : "chant"),
+        comment: args.comment ?? (run ? `chant run ${run.op} (${run.runId})` : "chant"),
+    };
+    const res = await f(`${url}/api/v2/silences`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) });
+    const text = await res.text();
+    if (!res.ok)
+        throw new Error(`POST ${url}/api/v2/silences: HTTP ${res.status}: ${text.slice(0, 300)}`);
+    const silenceId = JSON.parse(text).silenceID;
+    if (!silenceId)
+        throw new Error(`POST ${url}/api/v2/silences answered without a silenceID: ${text.slice(0, 300)}`);
+    const path = recordPath(args.record, args.recordDir);
+    writeRecord(path, [...readRecord(path), { silenceId, url, endsAt, ...(run ? { run: run.runId } : {}) }]);
+    return { silenceId, url, startsAt, endsAt, record: path };
+}
+/** Expire the recorded silences (or `silenceId`), and drop the expired ones from the record. */
+export async function alertmanagerUnsilence(args = {}) {
+    const f = args._fetch ?? fetch;
+    const path = recordPath(args.record, args.recordDir);
+    const recorded = readRecord(path);
+    const targets = args.silenceId
+        ? [recorded.find((s) => s.silenceId === args.silenceId) ?? { silenceId: args.silenceId, url: alertmanagerUrl(args.url), endsAt: "" }]
+        : recorded;
+    const expired = [];
+    const failed = [];
+    for (const s of targets) {
+        const base = args.url ? alertmanagerUrl(args.url) : s.url;
+        try {
+            const res = await f(`${base}/api/v2/silence/${encodeURIComponent(s.silenceId)}`, { method: "DELETE" });
+            const text = await res.text().catch(() => "");
+            // Alertmanager answers 404 for an unknown silence and 500 "already expired" for an expired one: both are done.
+            if (res.ok || res.status === 404 || /expired/i.test(text))
+                expired.push(s.silenceId);
+            else
+                failed.push({ silenceId: s.silenceId, detail: `HTTP ${res.status}: ${text.slice(0, 200)}` });
+        }
+        catch (err) {
+            failed.push({ silenceId: s.silenceId, detail: err.message });
+        }
+    }
+    const done = new Set(expired);
+    if (recorded.length > 0)
+        writeRecord(path, recorded.filter((s) => !done.has(s.silenceId)));
+    if (failed.length > 0) {
+        throw new Error(`could not expire ${failed.length} silence(s): ${failed.map((x) => `${x.silenceId} (${x.detail})`).join("; ")}`);
+    }
+    return { expired, failed };
+}

package/dist/op/activity-contracts.js

@@ -0,0 +1,51 @@
+/**
+ * Activity contracts for this lexicon's `op/activities` (#3369).
+ *
+ * Resolved by convention at
+ * `@intentius/chant-lexicon-prometheus/op/activity-contracts`:
+ * `loadActivityContracts` merges them into the map OPS012 checks each step's
+ * args against and OPS013 checks each step-output reference against. Every
+ * activity here has one; `rulesLoadedObserve`'s return schema is what lets a
+ * `ConvergeOp({ observe: rulesLoadedObserve(...) })` pass OPS013, and
+ * `alertmanagerSilence`'s is what a later step reads `.out.silenceId` from.
+ *
+ * Each `args` schema mirrors the `*Args` interface in `./activities/`,
+ * without the `_`-prefixed test seams, and is a `z.strictObject`, so a
+ * misspelled key fails the build.
+ */
+import { z } from "zod";
+import { activityContract } from "@intentius/chant/op";
+const oneOrMany = z.union([z.string(), z.array(z.string())]);
+const toolResult = z.object({ files: z.array(z.string()), ok: z.boolean(), output: z.string() });
+const resourceStatus = z.enum(["in-sync", "drifted", "unknown"]);
+export const promtoolCheckRulesContract = activityContract("promtoolCheckRules", z.strictObject({ rules: oneOrMany, bin: z.string().optional() }), toolResult);
+export const promtoolTestRulesContract = activityContract("promtoolTestRules", z.strictObject({ rules: z.string(), tests: oneOrMany.optional(), testYaml: oneOrMany.optional(), bin: z.string().optional() }), toolResult.extend({ tests: z.number() }));
+export const amtoolCheckConfigContract = activityContract("amtoolCheckConfig", z.strictObject({ config: z.string(), bin: z.string().optional() }), toolResult);
+export const amtoolRoutesTestContract = activityContract("amtoolRoutesTest", z.strictObject({ config: z.string(), labels: z.record(z.string(), z.string()), expect: oneOrMany, bin: z.string().optional() }), z.object({ config: z.string(), labels: z.record(z.string(), z.string()), receivers: z.array(z.string()), ok: z.boolean() }));
+const record = { record: z.string().optional(), recordDir: z.string().optional() };
+export const alertmanagerSilenceContract = activityContract("alertmanagerSilence", z.strictObject({
+    url: z.string().optional(),
+    matchers: z.union([z.array(z.string()), z.record(z.string(), z.string())]),
+    duration: z.string(),
+    comment: z.string().optional(),
+    createdBy: z.string().optional(),
+    ...record,
+}), z.object({ silenceId: z.string(), url: z.string(), startsAt: z.string(), endsAt: z.string(), record: z.string() }));
+export const alertmanagerUnsilenceContract = activityContract("alertmanagerUnsilence", z.strictObject({ url: z.string().optional(), silenceId: z.string().optional(), ...record }), z.object({ expired: z.array(z.string()), failed: z.array(z.object({ silenceId: z.string(), detail: z.string() })) }));
+export const rulesLoadedObserveContract = activityContract("rulesLoadedObserve", z.strictObject({ url: z.string().optional(), groups: z.array(z.string()).optional(), rules: oneOrMany.optional(), timeoutMs: z.number().optional() }), z.object({ resources: z.array(z.object({ name: z.string(), status: resourceStatus, detail: z.string() })) }));
+export const ruleAuditContract = activityContract("ruleAudit", z.strictObject({
+    url: z.string().optional(),
+    pendingFor: z.string().optional(),
+    firingFor: z.string().optional(),
+    selectorBudget: z.number().optional(),
+    lookback: z.string().optional(),
+    mode: z.enum(["report", "issue"]).optional(),
+    issueTitle: z.string().optional(),
+}), z.object({
+    mode: z.enum(["report", "issue"]),
+    findings: z.array(z.object({ kind: z.enum(["rule-error", "pending-too-long", "firing-too-long", "selector-no-series"]), subject: z.string(), detail: z.string() })),
+    queried: z.number(),
+    unchecked: z.number(),
+    summary: z.string(),
+    issueUrl: z.string().optional(),
+}));

package/dist/op/audit-op.js

@@ -0,0 +1,28 @@
+/**
+ * `RuleAuditOp`: what a live Prometheus says about its rules, as an Op with
+ * an optional schedule (#3369). One `ruleAudit` step reports groups with
+ * health errors, alerts pending or firing past a threshold, and selectors
+ * no live target emits (one query per selector, within a budget).
+ * `onFinding` is `report` (the default) or `issue`, which keeps one open
+ * issue current.
+ *
+ * @example
+ * ```typescript
+ * export const { op } = RuleAuditOp({ name: "rule-audit", url: "http://prometheus:9090", schedule: "0 * * * *" });
+ * ```
+ */
+import { Op, phase } from "@intentius/chant/op";
+import { ruleAudit } from "./builders.js";
+export function RuleAuditOp(config) {
+    const { name, schedule, onFinding, ...rest } = config;
+    const defined = Object.fromEntries(Object.entries(rest).filter(([, v]) => v !== undefined));
+    const step = ruleAudit({ mode: onFinding ?? "report", ...defined });
+    const op = Op({
+        name,
+        overview: "Audit a live Prometheus: rule health, alerts pending or firing too long, and selectors nothing emits",
+        labels: { Audit: "true", Surface: "prometheus-rules" },
+        ...(schedule ? { schedule: { cron: schedule, overlap: "skip" } } : {}),
+        phases: [phase("Audit", [{ ...step, outcomeAttribute: { name: "Findings", from: "findings" } }])],
+    });
+    return { op };
+}

package/dist/op/builders.js

@@ -0,0 +1,57 @@
+/**
+ * Typed step builders for this lexicon's Op activities (#3369), following
+ * the helm and fly builders: each one's options ARE the activity's own
+ * `*Args` interface (minus its `_`-prefixed test seams), every field also
+ * takes a `StepOutputRef`, and `profile` and `id` go to the step.
+ *
+ * `promtoolCheckRules`, `promtoolTestRules` and `amtoolCheckConfig` share
+ * their names with the plain functions in `../tools.ts`, which the package
+ * root already exports, so those three builders are reached here, at
+ * `@intentius/chant-lexicon-prometheus/op/builders`. The root exports the
+ * rest.
+ */
+import { activity, takeProfileAndId } from "@intentius/chant/op";
+import { sloRuleTests } from "./slo-rule-tests.js";
+function step(fn, defaultProfile) {
+    return (args) => {
+        const { args: rest, profile, id } = takeProfileAndId(args);
+        return activity(fn, rest, { profile: profile ?? defaultProfile, ...(id ? { id } : {}) });
+    };
+}
+/** `promtool check rules` over built rule files. Defaults to the `fastIdempotent` profile. */
+export const promtoolCheckRules = step("promtoolCheckRules", "fastIdempotent");
+/**
+ * `promtool test rules` over a built rule file. `slos` generates the tests
+ * from `Slo` declarations at build time (`sloRuleTests`): each burn-rate
+ * pair fires at its rate and not below it. Defaults to the `fastIdempotent`
+ * profile.
+ */
+export const promtoolTestRules = (args) => {
+    const { slos, ...rest } = args;
+    if (!slos || slos.length === 0)
+        return step("promtoolTestRules", "fastIdempotent")(rest);
+    const generated = sloRuleTests(slos);
+    const given = rest.testYaml === undefined ? [] : Array.isArray(rest.testYaml) ? rest.testYaml : [rest.testYaml];
+    return step("promtoolTestRules", "fastIdempotent")({ ...rest, testYaml: [...given, ...generated] });
+};
+/** `amtool check-config` over a built Alertmanager config. Defaults to the `fastIdempotent` profile. */
+export const amtoolCheckConfig = step("amtoolCheckConfig", "fastIdempotent");
+/** `amtool config routes test`: `labels` route to `expect`. Defaults to the `fastIdempotent` profile. */
+export const amtoolRoutesTest = step("amtoolRoutesTest", "fastIdempotent");
+/**
+ * Silence alerts through Alertmanager's API for `duration`, recording the
+ * silence id under `record` so `alertmanagerUnsilence` can expire it from
+ * a final phase or an `onFailure` phase. Defaults to the `atMostOnce`
+ * profile: a retry after a lost answer would create a second silence.
+ */
+export const alertmanagerSilence = step("alertmanagerSilence", "atMostOnce");
+/** Expire the silences `record` holds (or `silenceId`). Defaults to the `fastIdempotent` profile. */
+export const alertmanagerUnsilence = (args = {}) => step("alertmanagerUnsilence", "fastIdempotent")(args);
+/**
+ * Observe declared rule groups for a `ConvergeOp({ observe })`: one resource
+ * per group, drifted when Prometheus has not loaded it or a rule in it has
+ * `health: "err"`. Defaults to the `fastIdempotent` profile.
+ */
+export const rulesLoadedObserve = step("rulesLoadedObserve", "fastIdempotent");
+/** Audit a live Prometheus's rules, alerts and selectors (the step of `RuleAuditOp`). Defaults to the `fastIdempotent` profile. */
+export const ruleAudit = (args = {}) => step("ruleAudit", "fastIdempotent")(args);

package/dist/op/slo-rule-tests.js

@@ -0,0 +1,148 @@
+/**
+ * `promtool test rules` input generated from `Slo` declarations (#3369),
+ * lifted from `composites/slo-burn.test.ts`.
+ *
+ * For each burn-rate pair an `Slo` builds, two synthetic scenarios over a
+ * good and a bad request counter: healthy for the pair's long window, then
+ * burning the error budget at 1.25 times the pair's factor (it must fire)
+ * and at 0.9 times it (it must not). The small evaluator in `rule-eval.ts`
+ * runs the SLO's rules over each scenario and says which alerts fire at a
+ * few evaluation times around the expected onset; those become the
+ * `alert_rule_test` expectations, so `promtool test rules` holds Prometheus
+ * to the same answer.
+ *
+ * The SLI expressions are the author's, so the generator cannot invent the
+ * series they read: `good` and `bad` name one series each (`metric{labels}`),
+ * counters such that the SLI counts `good` as good events and `bad` as bad
+ * ones. The evaluator throws on PromQL it does not implement, which then
+ * fails here, at authoring time, rather than in promtool.
+ *
+ * Pairs whose long window is a day or more step in five minutes, the rest in
+ * one, and promtool's `evaluation_interval` is per file, so the result is
+ * one test file per step size.
+ */
+import { dump } from "js-yaml";
+import { sloMetrics } from "../composites/slo.js";
+import { ruleGroupConfig } from "../rules.js";
+import { RuleEvaluator } from "../rule-eval.js";
+import { durationMs } from "../duration.js";
+const MIN = 60000;
+/** `metric{a="1",b="2"}` as a label set with `__name__`. */
+export function seriesLabels(series) {
+    const m = /^\s*([A-Za-z_:][A-Za-z0-9_:]*)\s*(?:\{(.*)\})?\s*$/.exec(series);
+    if (!m)
+        throw new Error(`"${series}" is not a series: write metric{label="value",...}`);
+    const labels = { __name__: m[1] };
+    const body = m[2]?.trim();
+    if (body) {
+        const re = /\s*([A-Za-z_][A-Za-z0-9_]*)\s*=\s*"((?:[^"\\]|\\.)*)"\s*(?:,|$)/y;
+        let pos = 0;
+        while (pos < body.length) {
+            re.lastIndex = pos;
+            const p = re.exec(body);
+            if (!p)
+                throw new Error(`"${series}": label matchers must be name="value" (equality only)`);
+            labels[p[1]] = p[2].replace(/\\(.)/g, "$1");
+            pos = re.lastIndex;
+        }
+    }
+    return labels;
+}
+/** Counter samples as promtool's `a+bxn` segments. */
+export function seriesValues(values) {
+    const parts = [];
+    let i = 0;
+    while (i < values.length) {
+        const start = values[i];
+        if (i + 1 >= values.length) {
+            parts.push(`${start}`);
+            break;
+        }
+        const inc = values[i + 1] - values[i];
+        let j = i + 1;
+        while (j + 1 < values.length && Math.abs(values[j + 1] - values[j] - inc) < 1e-9)
+            j++;
+        parts.push(`${start}+${inc}x${j - i}`);
+        i = j + 1;
+    }
+    return parts.join(" ");
+}
+function isPair(a, b) {
+    return a.labels.alertname === b.alert && Object.entries(b.labels).every(([k, v]) => a.labels[k] === v);
+}
+const minutes = (d) => durationMs(d) / MIN;
+/** One scenario: the counters' samples, and the evaluator's firing alerts by minute. */
+function simulate(input, s) {
+    const m = sloMetrics(input.slo);
+    const rate = input.rate ?? 1000;
+    const goodLabels = seriesLabels(input.good);
+    const badLabels = seriesLabels(input.bad);
+    const ev = new RuleEvaluator([ruleGroupConfig(input.slo.rules)]);
+    const total = s.healthy + s.burning;
+    const good = [];
+    const bad = [];
+    let g = 0;
+    let e = 0;
+    const timeline = new Map();
+    for (let minute = 0; minute <= total; minute += s.step) {
+        if (minute > 0) {
+            const burning = minute > s.healthy && minute <= s.healthy + s.burning;
+            const b = burning ? rate * s.step * s.burn * m.errorBudget : 0;
+            e += b;
+            g += rate * s.step - b;
+        }
+        good.push(g);
+        bad.push(e);
+        ev.add(goodLabels, minute * MIN, g);
+        ev.add(badLabels, minute * MIN, e);
+        timeline.set(minute, ev.step(minute * MIN));
+    }
+    return { good, bad, timeline };
+}
+function testGroup(input, s, checkAt) {
+    const m = sloMetrics(input.slo);
+    const alertRules = ruleGroupConfig(input.slo.rules).rules.filter((r) => "alert" in r);
+    const { good, bad, timeline } = simulate(input, s);
+    return {
+        interval: `${s.step}m`,
+        input_series: [
+            { series: input.good, values: seriesValues(good) },
+            { series: input.bad, values: seriesValues(bad) },
+        ],
+        alert_rule_test: checkAt.map((minute) => ({
+            eval_time: `${minute}m`,
+            alertname: m.alertName,
+            exp_alerts: (timeline.get(minute) ?? [])
+                .filter((a) => a.labels.alertname === m.alertName)
+                .map((a) => {
+                const rule = alertRules.find((r) => Object.entries(r.labels ?? {}).every(([k, v]) => a.labels[k] === v));
+                const { alertname: _, ...labels } = a.labels;
+                return { exp_labels: labels, ...(rule?.annotations ? { exp_annotations: rule.annotations } : {}) };
+            }),
+        })),
+    };
+}
+/**
+ * The `promtool test rules` files for these SLOs, one per step size, each
+ * naming `rules.yml` (where `promtoolTestRules` writes the rule file).
+ */
+export function sloRuleTests(inputs) {
+    const byStep = new Map();
+    for (const input of inputs) {
+        for (const b of sloMetrics(input.slo).burnRates) {
+            const long = minutes(b.long);
+            const step = long >= 24 * 60 ? 5 : 1;
+            const snap = (x) => Math.round(x / step) * step;
+            const above = { step, healthy: long, burning: long, burn: b.factor * 1.25 };
+            const fireAt = above.healthy + ((long - step) * b.factor) / above.burn;
+            const below = { step, healthy: long, burning: long, burn: b.factor * 0.9 };
+            const groups = byStep.get(step) ?? [];
+            groups.push(testGroup(input, above, [snap(fireAt - 4 * step), snap(fireAt + 4 * step), above.healthy + long]));
+            groups.push(testGroup(input, below, [below.healthy + long]));
+            byStep.set(step, groups);
+        }
+    }
+    return [...byStep.entries()]
+        .sort(([a], [b]) => a - b)
+        .map(([step, tests]) => dump({ rule_files: ["rules.yml"], evaluation_interval: `${step}m`, tests }, { lineWidth: -1 }));
+}

package/dist/package-cli.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env tsx
+/**
+ * Thin entry point for `npm run bundle` in lexicon-prometheus.
+ */
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { writeBundleSpec } from "@intentius/chant/codegen/package";
+import { generate, writeGeneratedFiles } from "./codegen/generate.js";
+import { packageLexicon } from "./codegen/package.js";
+const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+writeGeneratedFiles(await generate({ verbose: true }));
+const { spec, stats } = await packageLexicon({ verbose: true });
+writeBundleSpec(spec, join(pkgDir, "dist"));
+console.error(`Packaged ${stats.resources} entities, ${stats.ruleCount} rules, ${stats.skillCount} skills`);

package/dist/pin.js

@@ -0,0 +1,13 @@
+/**
+ * The upstream releases this lexicon's hand-written types follow.
+ *
+ * Neither Prometheus nor Alertmanager publishes a machine-readable schema for
+ * its config files, so the types in `model.ts` are written against the Go
+ * structs of these releases (`prometheus/model/rulefmt`,
+ * `alertmanager/config`). Moving a version is a lexicon change like any
+ * other, released with this package.
+ */
+export const PROMETHEUS_PIN = Object.freeze({
+    prometheus: Object.freeze({ source: "github.com/prometheus/prometheus", version: "v3.15.0" }),
+    alertmanager: Object.freeze({ source: "github.com/prometheus/alertmanager", version: "v0.34.1" }),
+});

package/dist/plugin.js

@@ -0,0 +1,143 @@
+import { createDiffTool } from "@intentius/chant/lexicon-plugin-helpers";
+import { prometheusSerializer } from "./serializer.js";
+import { rules } from "./lint/rules/index.js";
+import { postSynthChecks } from "./lint/post-synth/index.js";
+import { OPT_IN_CHECKS, prometheusAuditCatalog } from "./lint/audit-catalog.js";
+import { completions } from "./lsp/completions.js";
+import { hover } from "./lsp/hover.js";
+import { detectTemplate } from "./detect.js";
+import { PrometheusParser } from "./import/parser.js";
+import { PrometheusGenerator } from "./import/generator.js";
+import { alertmanagerImporter, prometheusConfigImporter, ruleGroupsImporter } from "./import/embedded.js";
+import { DEFAULT_TEMPLATE, RULES_TEMPLATE, SLO_STYLE_TEMPLATE, SLO_TEMPLATE } from "./init-templates.js";
+import { prometheusSkills } from "./skill-defs.js";
+import { CATALOG } from "./catalog.js";
+import { PROMETHEUS_PIN } from "./pin.js";
+import { PROMQL_GRAMMAR } from "./promql.js";
+import { compositeCatalog } from "./composites/catalog.js";
+import { prometheusConfigSchema } from "./config.js";
+const catalogResource = {
+    uri: "prometheus:resource-catalog",
+    name: "Prometheus entity catalog",
+    description: "The rule group and Alertmanager entities this lexicon types, with the Prometheus and Alertmanager releases they follow",
+    mimeType: "application/json",
+    async handler() {
+        return JSON.stringify({ pin: PROMETHEUS_PIN, promql: PROMQL_GRAMMAR, entities: CATALOG });
+    },
+};
+/**
+ * Prometheus lexicon plugin.
+ *
+ * Typed recording and alerting rule groups, serialized to a Prometheus rule
+ * file, and Alertmanager routes, receivers, inhibit rules and time
+ * intervals, serialized to `alertmanager.yml`.
+ */
+export const prometheusPlugin = {
+    name: "prometheus",
+    serializer: prometheusSerializer,
+    configSchema: prometheusConfigSchema,
+    // ── Required lifecycle methods ────────────────────────────────
+    async generate(options) {
+        const { generate, writeGeneratedFiles } = await import("./codegen/generate.js");
+        writeGeneratedFiles(await generate(options));
+    },
+    async validate(_options) {
+        const { validate } = await import("./validate.js");
+        const { printValidationResult } = await import("@intentius/chant/codegen/validate");
+        printValidationResult(await validate());
+    },
+    async coverage(_options) {
+        const { prometheus, alertmanager } = PROMETHEUS_PIN;
+        console.error(`prometheus: ${CATALOG.length} entities`);
+        console.error(`  rule file (${prometheus.source} ${prometheus.version}): RuleGroup, recording and alerting rules`);
+        console.error(`  prometheus.yml (${prometheus.source} ${prometheus.version}): ScrapeConfig, PrometheusConfig`);
+        console.error(`  alertmanager.yml (${alertmanager.source} ${alertmanager.version}): ` +
+            CATALOG.filter((c) => c.file === "alertmanager.yml").map((c) => c.className).join(", "));
+        console.error("  receivers typed: webhook, email, slack, pagerduty");
+    },
+    async package(options) {
+        const { packageLexicon } = await import("./codegen/package.js");
+        const { writeBundleSpec } = await import("@intentius/chant/codegen/package");
+        const { join, dirname } = await import("path");
+        const { fileURLToPath } = await import("url");
+        const { spec, stats } = await packageLexicon(options);
+        const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+        writeBundleSpec(spec, join(pkgDir, "dist"));
+        console.error(`Packaged ${stats.resources} entities, ${stats.ruleCount} rules, ${stats.skillCount} skills`);
+    },
+    // ── Optional extensions ────────────────────────────────────
+    lintRules() {
+        return rules;
+    },
+    postSynthChecks() {
+        return postSynthChecks;
+    },
+    auditCatalog() {
+        return prometheusAuditCatalog;
+    },
+    /**
+     * `recommended` (what `chant build` reports by default) is every check but
+     * the opt-in ones; `all` adds them. A project turns one on with
+     * `lint.presets: { prometheus: "all" }`, or by naming it in `lint.rules`
+     * (`{ PROM212: "warning" }`), which keeps a check whatever the preset.
+     */
+    lintPresets() {
+        const all = Object.keys(prometheusAuditCatalog);
+        return { recommended: all.filter((id) => !OPT_IN_CHECKS.has(id)), all };
+    },
+    skills: prometheusSkills,
+    composites() {
+        return compositeCatalog;
+    },
+    mcpTools() {
+        return [
+            createDiffTool(prometheusSerializer, "Compare the current rule file and alertmanager.yml output against the previous build", "prometheus"),
+        ];
+    },
+    mcpResources() {
+        return [catalogResource];
+    },
+    detectTemplate(data) {
+        return detectTemplate(data);
+    },
+    templateParser() {
+        return new PrometheusParser();
+    },
+    templateGenerator() {
+        return new PrometheusGenerator();
+    },
+    embeddedImporters() {
+        return [ruleGroupsImporter, alertmanagerImporter, prometheusConfigImporter];
+    },
+    // `chant init --lexicon prometheus [--template rules|slo-style|slo]`; see ./init-templates.ts.
+    initTemplates(template) {
+        if (template === "rules")
+            return RULES_TEMPLATE;
+        if (template === "slo-style")
+            return SLO_STYLE_TEMPLATE;
+        if (template === "slo")
+            return SLO_TEMPLATE;
+        return DEFAULT_TEMPLATE;
+    },
+    completionProvider(ctx) {
+        return completions(ctx);
+    },
+    hoverProvider(ctx) {
+        return hover(ctx);
+    },
+    // ── Live observation and export (#3371) ──────────────────────
+    // Behind dynamic imports, so `chant build` never loads a transport. The
+    // ruler and Alertmanager are named by `prometheus.profiles.<env>` (./config.ts).
+    async describeResources(options) {
+        const { describeResources } = await import("./describe-resources.js");
+        return describeResources(options);
+    },
+    async exportResources(options) {
+        const { exportResources } = await import("./export-resources.js");
+        return exportResources(options);
+    },
+    async docs(options) {
+        const { generateDocs } = await import("./codegen/docs.js");
+        return generateDocs(options);
+    },
+};

package/dist/prometheus-config.js

@@ -0,0 +1,38 @@
+/**
+ * `PrometheusConfig` and `ScrapeConfig`: the entities that serialize to
+ * `prometheus.yml`.
+ *
+ * A `ScrapeConfig` is one scrape job. `PrometheusConfig` holds the rest of the
+ * file (`global`, `alerting`, `rule_files`, `remote_write`, `remote_read`,
+ * `otlp`) and is optional: a build that declares only `ScrapeConfig`s still
+ * writes a `prometheus.yml`. A project that declares neither writes none, so
+ * a project that builds only rule files sees no change.
+ */
+import { createResource } from "@intentius/chant/runtime";
+export const SCRAPE_CONFIG_TYPE = "Prometheus::Config::ScrapeConfig";
+export const PROMETHEUS_CONFIG_TYPE = "Prometheus::Config::PrometheusConfig";
+function entityClass(entityType, className) {
+    const Base = createResource(entityType, "prometheus", {});
+    const Cls = function (props) {
+        Base.call(this, (props ?? {}));
+    };
+    Object.defineProperty(Cls, "name", { value: className });
+    return Cls;
+}
+/**
+ * One scrape job: where its targets come from (`static_configs` or a service
+ * discovery list), how to scrape them, and how to relabel what comes back.
+ */
+export const ScrapeConfig = entityClass(SCRAPE_CONFIG_TYPE, "ScrapeConfig");
+/** The sections of `prometheus.yml` other than the scrape jobs. Declare at most one. */
+export const PrometheusConfig = entityClass(PROMETHEUS_CONFIG_TYPE, "PrometheusConfig");
+// ── Guards ──────────────────────────────────────────────────────────
+function isType(type) {
+    return (value) => typeof value === "object" && value !== null && value.entityType === type;
+}
+export const isScrapeConfig = isType(SCRAPE_CONFIG_TYPE);
+export const isPrometheusConfig = isType(PROMETHEUS_CONFIG_TYPE);
+/** True for an entity that goes into `prometheus.yml`. */
+export function isPrometheusConfigEntity(value) {
+    return isScrapeConfig(value) || isPrometheusConfig(value);
+}