@intentius/chant-lexicon-prometheus 0.96.0

package/src/alertmanager.ts

@@ -0,0 +1,143 @@
+/**
+ * Alertmanager entities: `Route`, `Receiver`, `InhibitRule`, `TimeInterval`
+ * and `AlertmanagerSettings`, which together serialize to `alertmanager.yml`.
+ *
+ * A route names its receiver and its time intervals either by the declared
+ * entity, which keeps the reference checked by TypeScript, or by name string
+ * for one declared somewhere chant can't see. PROM201 and PROM204 catch a
+ * string that names nothing declared.
+ *
+ * The routing tree is built from `Route`s: the root is the one route no other
+ * route lists as a child. Child routes may be `Route` entities or plain
+ * objects.
+ */
+
+import { createResource } from "@intentius/chant/runtime";
+import type { Declarable } from "@intentius/chant/declarable";
+import type {
+  AlertmanagerGlobalConfig,
+  InhibitRuleConfig,
+  ReceiverConfig,
+  RouteConfig,
+  TimeIntervalConfig,
+} from "./model";
+
+export const RECEIVER_TYPE = "Prometheus::Alertmanager::Receiver";
+export const ROUTE_TYPE = "Prometheus::Alertmanager::Route";
+export const INHIBIT_RULE_TYPE = "Prometheus::Alertmanager::InhibitRule";
+export const TIME_INTERVAL_TYPE = "Prometheus::Alertmanager::TimeInterval";
+export const SETTINGS_TYPE = "Prometheus::Alertmanager::Settings";
+
+type Ctor<P, E> = new (props: P) => E;
+
+function entityClass<P, E>(entityType: string, className: string, extra?: (self: object, props: P) => void): Ctor<P, E> {
+  const Base = createResource(entityType, "prometheus", {}) as unknown as (this: object, props: Record<string, unknown>) => void;
+  const Cls = function (this: object, props: P) {
+    Base.call(this, (props ?? {}) as unknown as Record<string, unknown>);
+    extra?.(this, props);
+  };
+  Object.defineProperty(Cls, "name", { value: className });
+  return Cls as unknown as Ctor<P, E>;
+}
+
+// ── Receiver ────────────────────────────────────────────────────────
+
+export type ReceiverProps = ReceiverConfig;
+
+export interface ReceiverEntity extends Declarable {
+  readonly props: ReceiverProps;
+  readonly receiverName: string;
+}
+
+/**
+ * A notification receiver: webhook, email, Slack and PagerDuty integrations.
+ *
+ * Credentials (Slack `api_url`, PagerDuty `routing_key`, SMTP passwords)
+ * belong in the `*_file` fields; Alertmanager does not expand environment
+ * variables in its config, and PROM001 flags a literal.
+ */
+export const Receiver = entityClass<ReceiverProps, ReceiverEntity>(RECEIVER_TYPE, "Receiver", (self, props) => {
+  Object.defineProperty(self, "receiverName", { value: props?.name, enumerable: false });
+});
+
+// ── TimeInterval ────────────────────────────────────────────────────
+
+export type TimeIntervalProps = TimeIntervalConfig;
+
+export interface TimeIntervalEntity extends Declarable {
+  readonly props: TimeIntervalProps;
+  readonly intervalName: string;
+}
+
+/** A named set of time periods a route can mute or activate on. */
+export const TimeInterval = entityClass<TimeIntervalProps, TimeIntervalEntity>(TIME_INTERVAL_TYPE, "TimeInterval", (self, props) => {
+  Object.defineProperty(self, "intervalName", { value: props?.name, enumerable: false });
+});
+
+// ── Route ───────────────────────────────────────────────────────────
+
+export type ReceiverRef = ReceiverEntity | string;
+export type TimeIntervalRef = TimeIntervalEntity | string;
+
+export interface RouteProps extends Omit<RouteConfig, "receiver" | "routes" | "mute_time_intervals" | "active_time_intervals"> {
+  /** The receiver alerts matching this route go to. Required on the root route. */
+  receiver?: ReceiverRef;
+  /** Child routes, tried in order. */
+  routes?: Array<RouteEntity | RouteProps>;
+  mute_time_intervals?: TimeIntervalRef[];
+  active_time_intervals?: TimeIntervalRef[];
+}
+
+export interface RouteEntity extends Declarable {
+  readonly props: RouteProps;
+}
+
+/** A node in the routing tree. Declare one root route; nest the rest under `routes`. */
+export const Route = entityClass<RouteProps, RouteEntity>(ROUTE_TYPE, "Route");
+
+// ── InhibitRule ─────────────────────────────────────────────────────
+
+export type InhibitRuleProps = InhibitRuleConfig;
+
+export interface InhibitRuleEntity extends Declarable {
+  readonly props: InhibitRuleProps;
+}
+
+/** Mutes alerts matching `target_matchers` while an alert matching `source_matchers` fires. */
+export const InhibitRule = entityClass<InhibitRuleProps, InhibitRuleEntity>(INHIBIT_RULE_TYPE, "InhibitRule");
+
+// ── AlertmanagerSettings ────────────────────────────────────────────
+
+export interface AlertmanagerSettingsProps {
+  global?: AlertmanagerGlobalConfig;
+  /** Paths of notification template files. */
+  templates?: string[];
+}
+
+export interface AlertmanagerSettingsEntity extends Declarable {
+  readonly props: AlertmanagerSettingsProps;
+}
+
+/** The `global:` block and `templates:` list. Optional; declare at most one. */
+export const AlertmanagerSettings = entityClass<AlertmanagerSettingsProps, AlertmanagerSettingsEntity>(
+  SETTINGS_TYPE,
+  "AlertmanagerSettings",
+);
+
+// ── Guards ──────────────────────────────────────────────────────────
+
+function isType<T>(type: string) {
+  return (value: unknown): value is T =>
+    typeof value === "object" && value !== null && (value as Declarable).entityType === type;
+}
+
+export const isReceiver = isType<ReceiverEntity>(RECEIVER_TYPE);
+export const isRoute = isType<RouteEntity>(ROUTE_TYPE);
+export const isInhibitRule = isType<InhibitRuleEntity>(INHIBIT_RULE_TYPE);
+export const isTimeInterval = isType<TimeIntervalEntity>(TIME_INTERVAL_TYPE);
+export const isAlertmanagerSettings = isType<AlertmanagerSettingsEntity>(SETTINGS_TYPE);
+
+/** True for any of the Alertmanager entity kinds. */
+export function isAlertmanagerEntity(value: unknown): boolean {
+  return isReceiver(value) || isRoute(value) || isInhibitRule(value) || isTimeInterval(value) || isAlertmanagerSettings(value);
+}

package/src/build.ts

@@ -0,0 +1,199 @@
+/**
+ * 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 type { Declarable } from "@intentius/chant/declarable";
+import { dump } from "js-yaml";
+import {
+  isAlertmanagerSettings,
+  isInhibitRule,
+  isReceiver,
+  isRoute,
+  isTimeInterval,
+  type AlertmanagerSettingsEntity,
+  type ReceiverEntity,
+  type RouteEntity,
+  type RouteProps,
+  type TimeIntervalEntity,
+} from "./alertmanager";
+import type {
+  AlertmanagerConfig,
+  InhibitRuleConfig,
+  ReceiverConfig,
+  RouteConfig,
+  RuleFileConfig,
+  TimeIntervalConfig,
+} from "./model";
+import { isRuleGroup, ruleGroupConfig, type RuleGroupEntity } from "./rules";
+
+function byName(a: unknown, b: unknown): number {
+  return String(a ?? "").localeCompare(String(b ?? ""));
+}
+
+function entityList(entities: Iterable<Declarable> | Map<string, Declarable>): Declarable[] {
+  return entities instanceof Map ? [...entities.values()] : [...entities];
+}
+
+/** A value with `undefined` keys dropped and entities left as they are. */
+function plain(value: unknown): unknown {
+  if (value === undefined) return undefined;
+  if (Array.isArray(value)) return value.map(plain);
+  if (typeof value === "object" && value !== null) {
+    const toJSON = (value as { toJSON?: () => unknown }).toJSON;
+    if (typeof toJSON === "function") return plain(toJSON.call(value));
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value)) {
+      if (v !== undefined) out[k] = plain(v);
+    }
+    return out;
+  }
+  return value;
+}
+
+// ── Rule file ───────────────────────────────────────────────────────
+
+export interface BuiltRuleFile {
+  config: RuleFileConfig;
+  groups: RuleGroupEntity[];
+}
+
+/** The rule file for a set of declared entities. Entities that aren't `RuleGroup`s are ignored. */
+export function buildRuleFile(entities: Iterable<Declarable> | Map<string, Declarable>): BuiltRuleFile {
+  const groups: RuleGroupEntity[] = [];
+  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 };
+}
+
+// ── alertmanager.yml ────────────────────────────────────────────────
+
+export interface BuiltAlertmanager {
+  config: AlertmanagerConfig;
+  /** Non-fatal problems, e.g. more than one root route. */
+  warnings: string[];
+  /** Every Alertmanager entity that took part, including ones reached only by reference. */
+  count: number;
+}
+
+function receiverName(ref: unknown): string {
+  return isReceiver(ref) ? ref.props.name : String(ref);
+}
+
+function intervalName(ref: unknown): string {
+  return isTimeInterval(ref) ? ref.props.name : String(ref);
+}
+
+function routeProps(route: RouteEntity | RouteProps): RouteProps {
+  return isRoute(route) ? route.props : route;
+}
+
+function routeConfig(route: RouteEntity | RouteProps): RouteConfig {
+  const p = routeProps(route);
+  const out: RouteConfig = {};
+  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.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: Iterable<Declarable> | Map<string, Declarable>): BuiltAlertmanager {
+  const all = entityList(entities);
+  const warnings: string[] = [];
+  const receivers: ReceiverEntity[] = [];
+  const intervals: TimeIntervalEntity[] = [];
+  const routes: RouteEntity[] = [];
+  const inhibits: InhibitRuleConfig[] = [];
+  let settings: AlertmanagerSettingsEntity | undefined;
+  let count = 0;
+
+  const addReceiver = (r: ReceiverEntity) => {
+    if (!receivers.includes(r)) receivers.push(r);
+  };
+  const addInterval = (t: TimeIntervalEntity) => {
+    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) as InhibitRuleConfig);
+    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<RouteEntity>();
+  const walk = (route: RouteEntity | RouteProps) => {
+    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: AlertmanagerConfig = {};
+  if (settings?.props.global) config.global = plain(settings.props.global) as AlertmanagerConfig["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) as ReceiverConfig);
+  if (intervals.length > 0) config.time_intervals = intervals.map((t) => plain(t.props) as TimeIntervalConfig);
+
+  return { config, warnings, count };
+}
+
+// ── YAML ────────────────────────────────────────────────────────────
+
+/** Print a rule file or Alertmanager config as YAML, keys in the order given. */
+export function emitYaml(value: unknown): string {
+  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: Iterable<Declarable> | Map<string, Declarable>): string {
+  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: Iterable<Declarable> | Map<string, Declarable>): string {
+  return emitYaml(buildAlertmanagerConfig(entities).config);
+}

package/src/catalog.ts

@@ -0,0 +1,65 @@
+/**
+ * The entity catalog: every class this package exports, keyed by class name.
+ * It feeds the packaged registry (`dist/meta.json`), LSP completions and
+ * hover, and the docs.
+ */
+
+import type { LexiconEntry } from "@intentius/chant/lsp/lexicon-providers";
+import { RULE_GROUP_TYPE } from "./rules";
+import { INHIBIT_RULE_TYPE, RECEIVER_TYPE, ROUTE_TYPE, SETTINGS_TYPE, TIME_INTERVAL_TYPE } from "./alertmanager";
+
+export interface CatalogEntry {
+  className: string;
+  entityType: string;
+  /** The file the entity serializes into. */
+  file: "rule file" | "alertmanager.yml";
+  description: string;
+}
+
+export const CATALOG: CatalogEntry[] = [
+  {
+    className: "RuleGroup",
+    entityType: RULE_GROUP_TYPE,
+    file: "rule file",
+    description: "A group of recording and alerting rules, evaluated together on one interval",
+  },
+  {
+    className: "Route",
+    entityType: ROUTE_TYPE,
+    file: "alertmanager.yml",
+    description: "A node in Alertmanager's routing tree: matchers, grouping and timing, and the receiver alerts go to",
+  },
+  {
+    className: "Receiver",
+    entityType: RECEIVER_TYPE,
+    file: "alertmanager.yml",
+    description: "A notification receiver with webhook, email, Slack and PagerDuty integrations",
+  },
+  {
+    className: "InhibitRule",
+    entityType: INHIBIT_RULE_TYPE,
+    file: "alertmanager.yml",
+    description: "Mutes alerts matching target_matchers while an alert matching source_matchers fires",
+  },
+  {
+    className: "TimeInterval",
+    entityType: TIME_INTERVAL_TYPE,
+    file: "alertmanager.yml",
+    description: "A named set of time periods a route can mute or activate on",
+  },
+  {
+    className: "AlertmanagerSettings",
+    entityType: SETTINGS_TYPE,
+    file: "alertmanager.yml",
+    description: "The global block (SMTP, Slack and PagerDuty defaults, resolve_timeout) and the templates list",
+  },
+];
+
+/** The catalog as a chant lexicon registry, keyed by class name. */
+export function lexiconRegistry(): Record<string, LexiconEntry> {
+  const out: Record<string, LexiconEntry> = {};
+  for (const e of [...CATALOG].sort((a, b) => a.className.localeCompare(b.className))) {
+    out[e.className] = { resourceType: e.entityType, kind: "resource", lexicon: "prometheus" };
+  }
+  return out;
+}

package/src/codegen/docs-cli.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env tsx
+import { generateDocs } from "./docs";
+
+await generateDocs({ verbose: true });

package/src/codegen/docs.ts

@@ -0,0 +1,104 @@
+/**
+ * Documentation generation for the prometheus lexicon: the generated
+ * reference pages from the core docs pipeline, plus the authored pages in
+ * docs/pages/.
+ */
+
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { docsPipeline, writeDocsSite, type DocsConfig } from "@intentius/chant/codegen/docs";
+
+function serviceFromType(resourceType: string): string {
+  const parts = resourceType.split("::");
+  return parts.length >= 2 ? parts[1] : "Prometheus";
+}
+
+const overview = `The prometheus lexicon types [Prometheus](https://prometheus.io/) recording and
+alerting rules and [Alertmanager](https://prometheus.io/docs/alerting/latest/alertmanager/)
+routing. \`chant build\` emits the rule file Prometheus loads through
+\`rule_files:\`, and the \`alertmanager.yml\` Alertmanager reads.
+
+\`\`\`ts
+import { RuleGroup, Route, Receiver } from "@intentius/chant-lexicon-prometheus";
+
+export const api = new RuleGroup({
+  name: "api",
+  rules: [
+    { record: "job:http_errors:ratio5m", expr: 'sum by (job) (rate(http_requests_total{code=~"5.."}[5m])) / sum by (job) (rate(http_requests_total[5m]))' },
+    { alert: "ApiErrors", expr: "job:http_errors:ratio5m > 0.05", for: "10m", labels: { severity: "page" }, annotations: { summary: "5xx ratio above 5%" } },
+  ],
+});
+
+export const oncall = new Receiver({ name: "oncall", pagerduty_configs: [{ routing_key_file: "/etc/alertmanager/secrets/pd-key" }] });
+export const fallback = new Receiver({ name: "fallback", webhook_configs: [{ url: "http://alert-sink:8080/" }] });
+export const root = new Route({ receiver: fallback, group_by: ["alertname", "job"], routes: [{ matchers: ['severity="page"'], receiver: oncall }] });
+\`\`\`
+
+The same \`RuleGroup\` renders into a Prometheus Operator \`PrometheusRule\`
+through the k8s lexicon, so rules are declared once whichever way Prometheus
+loads them.
+
+The \`Slo\` composite builds a service level objective to a \`RuleGroup\`:
+error ratios per window, the error budget left, and the SRE Workbook's
+multiwindow multi-burn-rate alerts. See [SLOs](./slos/).
+
+Checks run at build time: PromQL syntax in every \`expr\` (PROM104), unique
+group names (PROM101), valid durations (PROM103), routes that name
+declared receivers (PROM201), and every alert severity routed by some route
+(PROM202). \`promtool check rules\` and \`amtool check-config\` are wrapped as
+helpers for tests and CI, and run when installed.
+`;
+
+const outputFormat = `The prometheus lexicon serializes two files:
+
+- **The rule file**, from every \`RuleGroup\` in the build: \`groups:\`, each
+  with its \`name\`, optional \`interval\`, \`query_offset\`, \`limit\` and
+  \`labels\`, and its \`rules\`. This is the file \`rule_files:\` points at and
+  \`promtool check rules\` reads.
+- **\`alertmanager.yml\`**, from the \`AlertmanagerSettings\`, \`Route\`,
+  \`InhibitRule\`, \`Receiver\` and \`TimeInterval\` entities, in that section
+  order: \`global\`, \`templates\`, \`route\`, \`inhibit_rules\`, \`receivers\`,
+  \`time_intervals\`.
+
+The rule file is the primary output when the build declares any rule
+groups, and \`alertmanager.yml\` is written beside it (\`-o dist/rules.yml\`
+also writes \`dist/alertmanager.yml\`). A build with only Alertmanager
+entities emits \`alertmanager.yml\` as its primary output.
+
+- Rules inside a group and child routes keep the order they are written in,
+  which is the order Prometheus evaluates and Alertmanager matches them.
+  Groups, receivers and time intervals, whose order carries no meaning, are
+  sorted by name, so the files are the same however they were built. Keys
+  inside a rule come out in the order Prometheus documents them (\`record\`
+  or \`alert\`, \`expr\`, \`for\`, \`keep_firing_for\`, \`labels\`,
+  \`annotations\`).
+- A route references its receiver and time intervals by name in the output,
+  whether the declaration used the entity or a string.
+- The root route is the one \`Route\` no other route lists as a child.
+- Neither file has a metadata channel, so no ownership marker is stamped.
+`;
+
+export async function generateDocs(opts?: { verbose?: boolean }): Promise<void> {
+  const pkgDir = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+
+  const config: DocsConfig = {
+    name: "prometheus",
+    displayName: "Prometheus",
+    description: "Typed Prometheus rule groups and Alertmanager routing",
+    distDir: join(pkgDir, "dist"),
+    outDir: join(pkgDir, "docs"),
+    basePath: process.env.DOCS_BASE_PATH ?? "/chant/lexicons/prometheus/",
+    overview,
+    outputFormat,
+    serviceFromType,
+    srcDir: join(pkgDir, "src"),
+    examplesDir: join(pkgDir, "examples"),
+  };
+
+  const result = docsPipeline(config);
+  writeDocsSite(config, result);
+
+  if (opts?.verbose) {
+    console.error(`Generated ${result.pages.size} documentation pages`);
+  }
+}

package/src/codegen/generate-cli.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env tsx
+/**
+ * CLI entry point for `npm run generate` in lexicon-prometheus.
+ */
+import { generate, writeGeneratedFiles } from "./generate";
+
+const result = await generate({ verbose: true });
+writeGeneratedFiles(result);

package/src/codegen/generate.ts

@@ -0,0 +1,49 @@
+/**
+ * The prometheus lexicon's "generation" step.
+ *
+ * There is no upstream schema to fetch: Prometheus and Alertmanager define
+ * their config files as Go structs and publish no machine-readable schema for
+ * them. The types are written by hand against the releases in
+ * `PROMETHEUS_PIN` (src/pin.ts), and this step derives the registry from the
+ * entity catalog, so the packaged `dist/meta.json` can never disagree with
+ * the classes the package exports.
+ */
+
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { mkdirSync, writeFileSync } from "fs";
+import type { GenerateResult } from "@intentius/chant/codegen/generate";
+import { CATALOG, lexiconRegistry } from "../catalog";
+
+export type { GenerateResult };
+
+/** The packaged types entry re-exports the compiled declarations, which carry every config type. */
+const TYPES_DTS = `// The prometheus lexicon's entity classes and config types are hand-written in
+// src/ and compiled to dist/index.d.ts; this entry re-exports them.
+export * from "../index";
+`;
+
+export async function generate(opts?: { verbose?: boolean; force?: boolean }): Promise<GenerateResult> {
+  const registry = lexiconRegistry();
+  const lexiconJSON = `${JSON.stringify(registry, null, 2)}\n`;
+  if (opts?.verbose) {
+    console.error(`prometheus: ${CATALOG.length} entities (RuleGroup and the Alertmanager kinds)`);
+  }
+  return {
+    lexiconJSON,
+    typesDTS: TYPES_DTS,
+    indexTS: "",
+    resources: CATALOG.length,
+    properties: 0,
+    enums: 0,
+    warnings: [],
+  };
+}
+
+/** Write the registry to src/generated/lexicon-prometheus.json, for tools that read it from there. */
+export function writeGeneratedFiles(result: GenerateResult): void {
+  const pkgDir = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+  const dir = join(pkgDir, "src", "generated");
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, "lexicon-prometheus.json"), result.lexiconJSON);
+}

package/src/codegen/package.ts

@@ -0,0 +1,41 @@
+/**
+ * prometheus lexicon packaging, delegating to core's packagePipeline.
+ */
+
+import { readFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import {
+  packagePipeline,
+  collectSkills,
+  type PackageOptions,
+  type PackageResult,
+} from "@intentius/chant/codegen/package";
+import { generate } from "./generate";
+import { prometheusSkills } from "../skill-defs";
+
+export type { PackageOptions, PackageResult };
+
+// src/codegen/package.ts -> src/
+const srcDir = dirname(dirname(fileURLToPath(import.meta.url)));
+
+export async function packageLexicon(opts: PackageOptions = {}): Promise<PackageResult> {
+  const pkgJson = JSON.parse(readFileSync(join(srcDir, "..", "package.json"), "utf-8"));
+  return packagePipeline(
+    {
+      generate: (genOpts) => generate({ verbose: genOpts.verbose, force: genOpts.force }),
+      buildManifest: () => ({
+        name: "prometheus",
+        version: pkgJson.version ?? "0.0.1",
+        chantVersion: ">=0.1.0",
+        namespace: "Prometheus",
+        intrinsics: [],
+        pseudoParameters: {},
+      }),
+      srcDir,
+      collectSkills: () => collectSkills(prometheusSkills()),
+      version: pkgJson.version ?? "0.0.1",
+    },
+    opts,
+  );
+}

package/src/composites/catalog.test.ts

@@ -0,0 +1,37 @@
+/**
+ * The composite catalog matches what this lexicon exports (#2662).
+ *
+ * `catalog.ts` is generated by `npm run generate:composite-catalogs` and is
+ * what `chant serve mcp` lists.
+ */
+
+import { describe, expect, test } from "vitest";
+import { isCompositeDefinition } from "@intentius/chant";
+import * as composites from "./index";
+import { compositeCatalog } from "./catalog";
+import { prometheusPlugin } from "../plugin";
+
+const exported = Object.entries(composites)
+  .filter(([, value]) => isCompositeDefinition(value))
+  .map(([name]) => name)
+  .sort();
+const catalogued = compositeCatalog.map((entry) => entry.name).sort();
+
+describe("the prometheus composite catalog", () => {
+  test("every exported composite has an entry, and every entry names an exported composite", () => {
+    expect(exported).toEqual(["Slo"]);
+    expect(catalogued, "regenerate with `npm run generate:composite-catalogs -- prometheus`").toEqual(exported);
+  });
+
+  test("every entry says what it is and what it bundles", () => {
+    for (const entry of compositeCatalog) {
+      expect(entry.lexicon, entry.name).toBe("prometheus");
+      expect(entry.description.length, entry.name).toBeGreaterThan(0);
+      expect(entry.bundles, entry.name).toEqual(["RuleGroup"]);
+    }
+  });
+
+  test("the plugin contributes it", () => {
+    expect(prometheusPlugin.composites?.()).toBe(compositeCatalog);
+  });
+});