@intentius/chant-lexicon-prometheus 0.96.0

package/src/lsp/hover.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from "vitest";
+import { hover } from "./hover";
+
+describe("prometheus LSP hover", () => {
+  it("describes RuleGroup and the file it lands in", () => {
+    const info = hover({
+      uri: "file:///rules.ts",
+      content: "new RuleGroup({})",
+      position: { line: 0, character: 6 },
+      word: "RuleGroup",
+      lineText: "new RuleGroup({})",
+    });
+    expect(info?.contents).toContain("Prometheus::Rules::RuleGroup");
+    expect(info?.contents).toContain("rule file");
+    expect(info?.contents).toContain("v3.15.0");
+  });
+
+  it("describes an Alertmanager entity against the Alertmanager pin", () => {
+    const info = hover({ uri: "file:///am.ts", content: "new Receiver({})", position: { line: 0, character: 6 }, word: "Receiver", lineText: "new Receiver({})" });
+    expect(info?.contents).toContain("alertmanager.yml");
+    expect(info?.contents).toContain("v0.34.1");
+  });
+
+  it("returns undefined for an unknown word", () => {
+    expect(hover({ uri: "file:///x.ts", content: "", position: { line: 0, character: 0 }, word: "Nope", lineText: "" })).toBeUndefined();
+  });
+});

package/src/lsp/hover.ts

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

package/src/matchers.ts

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

package/src/model.test.ts

@@ -0,0 +1,104 @@
+import { describe, expect, test } from "vitest";
+import { durationMs, formatDuration, isValidDuration } from "./duration";
+import { matcher, matcherMatches, parseMatchers, type Matcher } from "./matchers";
+import { checkPromql } from "./promql";
+import { looksLikeAlertmanagerConfig, looksLikeRuleFile } from "./model";
+
+describe("durations", () => {
+  test.each(["0", "30s", "5m", "1h30m", "1d", "2w", "1y", "500ms", "1h0m0s", "1y2w3d4h5m6s7ms"])("%s is valid", (d) => {
+    expect(isValidDuration(d)).toBe(true);
+  });
+
+  test.each(["", "5", "1.5h", "30m1h", "5 m", "5min", "-1m", "1h1h", "m"])("%j is not", (d) => {
+    expect(isValidDuration(d)).toBe(false);
+  });
+
+  test("durationMs and formatDuration agree", () => {
+    expect(durationMs("1h30m")).toBe(5_400_000);
+    expect(durationMs("2d")).toBe(172_800_000);
+    expect(durationMs("nope")).toBeUndefined();
+    expect(formatDuration(5_400_000)).toBe("1h30m");
+    expect(formatDuration(0)).toBe("0s");
+    for (const d of ["28d", "6h", "30m", "1h5m", "4w"]) expect(durationMs(formatDuration(durationMs(d)!))).toBe(durationMs(d));
+    expect(() => formatDuration(1.5)).toThrow();
+  });
+});
+
+describe("matchers", () => {
+  test("parses the four operators, quoted and unquoted", () => {
+    expect(parseMatchers('severity="page"')).toEqual({ ok: true, matchers: [{ name: "severity", op: "=", value: "page" }] });
+    expect(parseMatchers("severity!=info")).toEqual({ ok: true, matchers: [{ name: "severity", op: "!=", value: "info" }] });
+    expect(parseMatchers('team=~"db|infra"')).toMatchObject({ ok: true, matchers: [{ op: "=~" }] });
+    expect(parseMatchers('env!~"dev.*"')).toMatchObject({ ok: true, matchers: [{ op: "!~" }] });
+  });
+
+  test("parses a braced list and quoted commas", () => {
+    const r = parseMatchers('{severity="page", msg="a, b"}');
+    expect(r).toEqual({ ok: true, matchers: [{ name: "severity", op: "=", value: "page" }, { name: "msg", op: "=", value: "a, b" }] });
+  });
+
+  test.each(['severity', '="x"', 'sev-erity="x"', 'a="unterminated', 'a=~"("', "{a=b", "a=b c=d"])("rejects %j", (m) => {
+    expect(parseMatchers(m).ok).toBe(false);
+  });
+
+  test("matches like Alertmanager, regexes anchored, missing labels empty", () => {
+    const one = (s: string): Matcher => {
+      const r = parseMatchers(s);
+      if (!r.ok) throw new Error(r.error);
+      return r.matchers[0];
+    };
+    const [eq, re, ne] = [one('severity="page"'), one('severity=~"pa"'), one('team!=""')];
+    expect(matcherMatches(eq, { severity: "page" })).toBe(true);
+    expect(matcherMatches(re, { severity: "page" })).toBe(false);
+    expect(matcherMatches(ne, {})).toBe(false);
+  });
+
+  test("matcher() quotes the value", () => {
+    expect(matcher("severity", "=", "page")).toBe('severity="page"');
+    expect(parseMatchers(matcher("msg", "=", 'say "hi"'))).toMatchObject({ ok: true, matchers: [{ value: 'say "hi"' }] });
+  });
+});
+
+describe("PromQL syntax", () => {
+  test.each([
+    'sum by (job) (rate(http_requests_total{job="api"}[5m])) > 0.1',
+    "histogram_quantile(0.99, sum by (le) (rate(http_request_duration_seconds_bucket[5m])))",
+    "1 - (sum(rate(good[1h])) / sum(rate(total[1h])))",
+    'absent(up{job="api"} == 1)',
+    "rate(x[5m:1m]) offset 1h",
+    "a and on (job) b",
+    "up\n  == 0",
+  ])("accepts %s", (q) => {
+    expect(checkPromql(q)).toEqual({ ok: true });
+  });
+
+  test.each([
+    ["rate(x[5m]", "ends early"],
+    ["x{a=\"b\"", "ends early"],
+    ["foo bar", "offset 4"],
+    ["rate(x[5q])", "syntax error"],
+    ["notafunction(x)", "syntax error"],
+    ['sum(rate(x[{{window}}]))', "syntax error"],
+    ["", "empty"],
+  ])("rejects %j", (q, msg) => {
+    const r = checkPromql(q);
+    expect(r.ok).toBe(false);
+    if (!r.ok) expect(r.message).toContain(msg);
+  });
+});
+
+describe("document shape", () => {
+  test("rule files", () => {
+    expect(looksLikeRuleFile({ groups: [] })).toBe(true);
+    expect(looksLikeRuleFile({ groups: [{ name: "a", rules: [] }] })).toBe(true);
+    expect(looksLikeRuleFile({ groups: [{ name: "a" }] })).toBe(false);
+    expect(looksLikeRuleFile({ spec: { groups: [] } })).toBe(false);
+  });
+
+  test("alertmanager configs", () => {
+    expect(looksLikeAlertmanagerConfig({ route: { receiver: "a" } })).toBe(true);
+    expect(looksLikeAlertmanagerConfig({ receivers: [] })).toBe(true);
+    expect(looksLikeAlertmanagerConfig({ apiVersion: "v1", kind: "Receiver", receivers: [] })).toBe(false);
+    expect(looksLikeAlertmanagerConfig({ receivers: { otlp: {} } })).toBe(false);
+  });
+});

package/src/model.ts

@@ -0,0 +1,290 @@
+/**
+ * The plain-data model of a Prometheus rule file and an Alertmanager config.
+ *
+ * Everything else in this lexicon reads or writes these shapes: the serializer
+ * builds them from declared entities, the YAML emitter prints them, the checks
+ * validate them, and other lexicons (the k8s `PrometheusRule`, the SLO
+ * composite, Grafana panels) read them. They are exactly the files' own
+ * layouts, so a parsed rule file or `alertmanager.yml` already is one and
+ * needs no conversion.
+ *
+ * Field names keep the files' snake_case (`keep_firing_for`, `group_wait`),
+ * so a declaration reads the same as the file it produces and the upstream
+ * docs apply word for word.
+ */
+
+/** Labels or annotations: string keys to string values. */
+export type LabelSet = Record<string, string>;
+
+/** A recording rule: evaluates `expr` and stores the result as the series `record`. */
+export interface RecordingRuleConfig {
+  /** The metric name the result is stored under, e.g. `job:http_requests:rate5m`. */
+  record: string;
+  /** The PromQL expression. */
+  expr: string;
+  /** Labels added to the stored series. */
+  labels?: LabelSet;
+}
+
+/** An alerting rule: fires while `expr` returns anything, after `for`. */
+export interface AlertingRuleConfig {
+  /** The alert name, the `alertname` label on every alert it fires. */
+  alert: string;
+  /** The PromQL expression. Every series it returns is one alert. */
+  expr: string;
+  /** How long the expression must hold before the alert fires, e.g. `5m`. */
+  for?: string;
+  /** How long the alert keeps firing after the expression stops returning it. */
+  keep_firing_for?: string;
+  /** Labels added to the alert. Alertmanager routes on these; set `severity`. */
+  labels?: LabelSet;
+  /** Annotations added to the alert, e.g. `summary`, `description`, `runbook_url`. */
+  annotations?: LabelSet;
+}
+
+export type RuleConfig = RecordingRuleConfig | AlertingRuleConfig;
+
+/** One entry under `groups:` in a rule file, and one entry in a `PrometheusRule`'s `spec.groups`. */
+export interface RuleGroupConfig {
+  name: string;
+  /** How often the group is evaluated. Defaults to the global `evaluation_interval`. */
+  interval?: string;
+  /** Evaluate the group this far in the past, for late-arriving data. */
+  query_offset?: string;
+  /** Cap on alerts (alerting rules) or series (recording rules) a rule may produce; 0 is no limit. */
+  limit?: number;
+  /** Labels added to every rule in the group. A rule's own labels win. */
+  labels?: LabelSet;
+  rules: RuleConfig[];
+}
+
+/** A whole rule file, the YAML `rule_files:` points at and `promtool check rules` reads. */
+export interface RuleFileConfig {
+  groups: RuleGroupConfig[];
+}
+
+export function isRecordingRuleConfig(rule: unknown): rule is RecordingRuleConfig {
+  return typeof rule === "object" && rule !== null && typeof (rule as { record?: unknown }).record === "string";
+}
+
+export function isAlertingRuleConfig(rule: unknown): rule is AlertingRuleConfig {
+  return typeof rule === "object" && rule !== null && typeof (rule as { alert?: unknown }).alert === "string";
+}
+
+/** The rule's name: `record` for a recording rule, `alert` for an alerting rule. */
+export function ruleName(rule: RuleConfig): string {
+  return isRecordingRuleConfig(rule) ? rule.record : (rule as AlertingRuleConfig).alert;
+}
+
+// ── Alertmanager ────────────────────────────────────────────────────
+
+/** HTTP client settings shared by the receivers that make HTTP calls. */
+export interface HttpClientConfig {
+  basic_auth?: { username?: string; username_file?: string; password?: string; password_file?: string };
+  authorization?: { type?: string; credentials?: string; credentials_file?: string };
+  bearer_token?: string;
+  bearer_token_file?: string;
+  oauth2?: Record<string, unknown>;
+  proxy_url?: string;
+  follow_redirects?: boolean;
+  enable_http2?: boolean;
+  tls_config?: {
+    ca_file?: string;
+    cert_file?: string;
+    key_file?: string;
+    server_name?: string;
+    insecure_skip_verify?: boolean;
+    min_version?: string;
+  };
+}
+
+interface NotifierBase {
+  /** Whether to notify about resolved alerts too. */
+  send_resolved?: boolean;
+}
+
+export interface WebhookConfig extends NotifierBase {
+  /** Where alerts are POSTed. Set this or `url_file`. */
+  url?: string;
+  url_file?: string;
+  http_config?: HttpClientConfig;
+  /** Most alerts per message; 0 sends them all. */
+  max_alerts?: number;
+  timeout?: string;
+}
+
+export interface EmailConfig extends NotifierBase {
+  to: string;
+  from?: string;
+  /** `host:port` of the SMTP server. Falls back to `global.smtp_smarthost`. */
+  smarthost?: string;
+  hello?: string;
+  auth_username?: string;
+  auth_password?: string;
+  auth_password_file?: string;
+  auth_secret?: string;
+  auth_secret_file?: string;
+  auth_identity?: string;
+  require_tls?: boolean;
+  tls_config?: HttpClientConfig["tls_config"];
+  html?: string;
+  text?: string;
+  headers?: Record<string, string>;
+}
+
+export interface SlackConfig extends NotifierBase {
+  /** The incoming-webhook URL. It is a credential: prefer `api_url_file`. */
+  api_url?: string;
+  api_url_file?: string;
+  channel?: string;
+  username?: string;
+  color?: string;
+  title?: string;
+  title_link?: string;
+  pretext?: string;
+  text?: string;
+  footer?: string;
+  fallback?: string;
+  icon_emoji?: string;
+  icon_url?: string;
+  link_names?: boolean;
+  short_fields?: boolean;
+  mrkdwn_in?: string[];
+  fields?: Array<{ title: string; value: string; short?: boolean }>;
+  actions?: Array<Record<string, unknown>>;
+  http_config?: HttpClientConfig;
+}
+
+export interface PagerDutyConfig extends NotifierBase {
+  /** Events API v2 integration key. A credential: prefer `routing_key_file`. */
+  routing_key?: string;
+  routing_key_file?: string;
+  /** Events API v1 integration key. A credential: prefer `service_key_file`. */
+  service_key?: string;
+  service_key_file?: string;
+  url?: string;
+  client?: string;
+  client_url?: string;
+  description?: string;
+  severity?: string;
+  class?: string;
+  component?: string;
+  group?: string;
+  source?: string;
+  details?: Record<string, string>;
+  links?: Array<{ href: string; text?: string }>;
+  images?: Array<{ src: string; alt?: string; href?: string }>;
+  http_config?: HttpClientConfig;
+}
+
+/** One entry under `receivers:`. */
+export interface ReceiverConfig {
+  name: string;
+  webhook_configs?: WebhookConfig[];
+  email_configs?: EmailConfig[];
+  slack_configs?: SlackConfig[];
+  pagerduty_configs?: PagerDutyConfig[];
+}
+
+/** A route in the routing tree. The top-level `route:` is the root. */
+export interface RouteConfig {
+  receiver?: string;
+  group_by?: string[];
+  continue?: boolean;
+  /** Matchers in Alertmanager's syntax, e.g. `severity="critical"` or `team=~"db|infra"`. */
+  matchers?: string[];
+  group_wait?: string;
+  group_interval?: string;
+  repeat_interval?: string;
+  mute_time_intervals?: string[];
+  active_time_intervals?: string[];
+  routes?: RouteConfig[];
+}
+
+/** One entry under `inhibit_rules:`. */
+export interface InhibitRuleConfig {
+  source_matchers?: string[];
+  target_matchers?: string[];
+  /** Labels that must be equal on source and target for the inhibition to apply. */
+  equal?: string[];
+}
+
+export interface TimeRangeConfig {
+  start_time: string;
+  end_time: string;
+}
+
+/** One period inside a time interval. Every field left out matches everything. */
+export interface TimePeriodConfig {
+  times?: TimeRangeConfig[];
+  /** e.g. `monday:friday`, `saturday`. */
+  weekdays?: string[];
+  /** e.g. `1:5`, `-1`. */
+  days_of_month?: string[];
+  /** e.g. `january:march`, `12`. */
+  months?: string[];
+  /** e.g. `2026:2027`. */
+  years?: string[];
+  /** An IANA time zone name, e.g. `Europe/Berlin`. Defaults to UTC. */
+  location?: string;
+}
+
+/** One entry under `time_intervals:`. */
+export interface TimeIntervalConfig {
+  name: string;
+  time_intervals: TimePeriodConfig[];
+}
+
+/** `global:` settings. */
+export interface AlertmanagerGlobalConfig {
+  resolve_timeout?: string;
+  smtp_from?: string;
+  smtp_smarthost?: string;
+  smtp_hello?: string;
+  smtp_auth_username?: string;
+  smtp_auth_password?: string;
+  smtp_auth_password_file?: string;
+  smtp_auth_secret?: string;
+  smtp_auth_secret_file?: string;
+  smtp_auth_identity?: string;
+  smtp_require_tls?: boolean;
+  slack_api_url?: string;
+  slack_api_url_file?: string;
+  pagerduty_url?: string;
+  http_config?: HttpClientConfig;
+}
+
+/** A whole `alertmanager.yml`, the file `amtool check-config` reads. */
+export interface AlertmanagerConfig {
+  global?: AlertmanagerGlobalConfig;
+  templates?: string[];
+  route?: RouteConfig;
+  inhibit_rules?: InhibitRuleConfig[];
+  receivers?: ReceiverConfig[];
+  time_intervals?: TimeIntervalConfig[];
+}
+
+/** The four receiver integrations this lexicon types. */
+export const RECEIVER_INTEGRATIONS = ["webhook_configs", "email_configs", "slack_configs", "pagerduty_configs"] as const;
+
+/** True when a parsed document has the shape of a Prometheus rule file. */
+export function looksLikeRuleFile(value: unknown): value is RuleFileConfig {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const groups = (value as Record<string, unknown>).groups;
+  if (!Array.isArray(groups)) return false;
+  return groups.every(
+    (g) => typeof g === "object" && g !== null && typeof (g as Record<string, unknown>).name === "string" && Array.isArray((g as Record<string, unknown>).rules),
+  );
+}
+
+/** True when a parsed document has the shape of an `alertmanager.yml`. */
+export function looksLikeAlertmanagerConfig(value: unknown): value is AlertmanagerConfig {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const v = value as Record<string, unknown>;
+  const route = v.route;
+  const receivers = v.receivers;
+  const hasRoute = typeof route === "object" && route !== null && !Array.isArray(route);
+  const hasReceivers = Array.isArray(receivers);
+  // A k8s manifest never has both at the top level; a collector config has neither.
+  return (hasRoute || hasReceivers) && !("apiVersion" in v) && !("kind" in v);
+}

package/src/package-cli.ts

@@ -0,0 +1,17 @@
+#!/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";
+import { packageLexicon } from "./codegen/package";
+
+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/src/pin.ts

@@ -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/src/plugin.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, it } from "vitest";
+import { isLexiconPlugin } from "@intentius/chant/lexicon";
+import { prometheusPlugin } from "./plugin";
+import { prometheusAuditCatalog } from "./lint/audit-catalog";
+
+describe("prometheus plugin", () => {
+  it("is a valid LexiconPlugin", () => {
+    expect(isLexiconPlugin(prometheusPlugin)).toBe(true);
+  });
+
+  it("is named prometheus and serializes under the PROM prefix", () => {
+    expect(prometheusPlugin.name).toBe("prometheus");
+    expect(prometheusPlugin.serializer.name).toBe("prometheus");
+    expect(prometheusPlugin.serializer.rulePrefix).toBe("PROM");
+    expect(prometheusPlugin.serializer.extraRulePrefixes).toBeUndefined();
+  });
+
+  it("ships lint rules and post-synth checks, all under the PROM prefix", () => {
+    const ids = [...prometheusPlugin.lintRules!().map((r) => r.id), ...prometheusPlugin.postSynthChecks!().map((c) => c.id)];
+    expect(ids).toEqual([
+      "PROM001",
+      "PROM002",
+      "PROM003",
+      "PROM101",
+      "PROM102",
+      "PROM103",
+      "PROM104",
+      "PROM105",
+      "PROM106",
+      "PROM107",
+      "PROM201",
+      "PROM202",
+      "PROM203",
+      "PROM204",
+      "PROM205",
+      "PROM206",
+      "PROM207",
+      "PROM208",
+      "PROM209",
+    ]);
+  });
+
+  it("catalogues every rule and post-synth check for chant audit, and nothing else", () => {
+    const ids = [...prometheusPlugin.lintRules!().map((r) => r.id), ...prometheusPlugin.postSynthChecks!().map((c) => c.id)];
+    expect(Object.keys(prometheusAuditCatalog).sort()).toEqual([...ids].sort());
+  });
+
+  it("detects a rule file and an alertmanager.yml, and nothing else", () => {
+    expect(prometheusPlugin.detectTemplate!({ groups: [{ name: "a", rules: [] }] })).toBe(true);
+    expect(prometheusPlugin.detectTemplate!({ route: { receiver: "x" }, receivers: [{ name: "x" }] })).toBe(true);
+    expect(prometheusPlugin.detectTemplate!({ apiVersion: "v1", kind: "ConfigMap" })).toBe(false);
+    expect(prometheusPlugin.detectTemplate!({ receivers: { otlp: {} }, service: { pipelines: {} } })).toBe(false);
+    expect(prometheusPlugin.detectTemplate!({ groups: "nope" })).toBe(false);
+  });
+
+  it("loads its skills with content", () => {
+    const skills = prometheusPlugin.skills!();
+    expect(skills.map((s) => s.name)).toEqual(["chant-prometheus", "chant-prometheus-alertmanager", "chant-prometheus-kubernetes"]);
+    for (const s of skills) expect(s.content.length).toBeGreaterThan(100);
+  });
+
+  it("registers namespaced MCP contributions", () => {
+    expect(prometheusPlugin.mcpTools!().map((t) => t.name)).toEqual(["prometheus:diff"]);
+    expect(prometheusPlugin.mcpResources!().map((r) => r.uri)).toEqual(["prometheus:resource-catalog"]);
+  });
+
+  it("serves the catalog with its pins", async () => {
+    const body = JSON.parse(await prometheusPlugin.mcpResources!()[0].handler());
+    expect(body.pin.prometheus.version).toBe("v3.15.0");
+    expect(body.pin.alertmanager.version).toBe("v0.34.1");
+    expect(body.entities.map((e: { className: string }) => e.className)).toContain("RuleGroup");
+  });
+});