@intentius/chant-lexicon-prometheus 0.97.0 → 0.99.0

package/src/lint/rules/promql-literal.ts

@@ -1,6 +1,6 @@
 import * as ts from "typescript";
 import type { LintRule, LintDiagnostic, LintContext } from "@intentius/chant/lint/rule";
-import { calleeName, literalText, position, propertyName } from "./prom-ast";
+import { calleeName, constInitializers, literalText, position, propertyName, resolveConst } from "./prom-ast";
 import { checkPromql } from "../../promql";
 
 /**
@@ -21,7 +21,21 @@ export const promqlLiteralRule: LintRule = {
     const diagnostics: LintDiagnostic[] = [];
     const source = context.sourceFile;
 
+    const consts = constInitializers(source);
+    const scanned = new Set<ts.Node>();
+
+    // Rules lifted into a const (`rules: apiRules`) are followed to it and
+    // checked where the group uses them.
+    const follow = (value: ts.Expression) => {
+      const init = resolveConst(value, consts);
+      if (init !== value && !scanned.has(init)) {
+        scanned.add(init);
+        scan(init);
+      }
+    };
     const scan = (node: ts.Node) => {
+      if (ts.isShorthandPropertyAssignment(node)) follow(node.name);
+      if (ts.isPropertyAssignment(node) && ts.isIdentifier(node.initializer)) follow(node.initializer);
       if (ts.isPropertyAssignment(node) && propertyName(node) === "expr") {
         const text = literalText(node.initializer);
         if (text !== undefined) {

package/src/lint/rules/rules.test.ts

@@ -44,6 +44,52 @@ describe("PROM001 literal credential", () => {
     );
     expect(diags).toEqual([]);
   });
+
+  test("follows values lifted into named consts, shorthand props and spreads", () => {
+    const diags = literalCredentialRule.check(
+      ctx(`
+        const heartbeatEmail: EmailConfig[] = [{ to: "a@example.com", auth_password: "hunter2" }];
+        const heartbeat = new Receiver({ name: "heartbeat", email_configs: heartbeatEmail });
+        const oncallUntyped = { opsgenie_configs: [{ api_key: "x" }], pagerduty_configs: [{ service_key: "k" }] };
+        const oncall = new Receiver({ name: "oncall", ...oncallUntyped });
+        const global: AlertmanagerGlobalConfig = { smtp_auth_password: "p" };
+        const settings = new AlertmanagerSettings({ global });
+        const safe: PagerDutyConfig[] = [{ routing_key_file: "/etc/pd" }];
+        const pager = new Receiver({ name: "pager", pagerduty_configs: safe });
+      `),
+    );
+    expect(diags.map((d) => d.message.split("`")[1])).toEqual(["auth_password", "api_key", "service_key", "smtp_auth_password"]);
+  });
+
+  test("covers every integration's credential, and api_url and routing_key only where they are one", () => {
+    const diags = literalCredentialRule.check(
+      ctx(`
+        const chatSlack: SlackConfig[] = [{ api_url: "https://hooks.slack.com/services/T/B/X", app_token: "xoxb-1" }];
+        new Receiver({
+          name: "chat",
+          slack_configs: chatSlack,
+          discord_configs: [{ webhook_url: "https://discord.com/api/webhooks/1/x" }],
+          telegram_configs: [{ bot_token: "123:abc", chat_id: 1 }],
+          webex_configs: [{ api_url: "https://webexapis.com/v1/messages", room_id: "r" }],
+          victorops_configs: [{ api_key: "k", routing_key: "ops" }],
+          pushover_configs: [{ user_key: "u", token: "t" }],
+          rocketchat_configs: [{ token_id: "i", token_file: "/etc/rc" }],
+        });
+        new AlertmanagerSettings({ global: { telegram_bot_token: "123:abc", webex_api_url: "https://webexapis.com/v1/messages" } });
+      `),
+    );
+    expect(diags.map((d) => d.message.split("`")[1])).toEqual([
+      "api_url",
+      "app_token",
+      "webhook_url",
+      "bot_token",
+      "api_key",
+      "user_key",
+      "token",
+      "token_id",
+      "telegram_bot_token",
+    ]);
+  });
 });
 
 describe("PROM002 PromQL literal", () => {
@@ -61,6 +107,18 @@ describe("PROM002 PromQL literal", () => {
     expect(diags[0].line).toBe(3);
   });
 
+  test("follows rules lifted into a named const", () => {
+    const diags = promqlLiteralRule.check(
+      ctx(`
+        const apiRules: Rule[] = [{ record: "a:b", expr: "sum(" }, { alert: "A", expr: "up == 0" }];
+        const api = new RuleGroup({ name: "api", rules: apiRules });
+        const rules: Rule[] = [{ record: "c:d", expr: "rate(x[5m]" }];
+        const other = new RuleGroup({ name: "other", rules });
+      `),
+    );
+    expect(diags.map((d) => d.line)).toEqual([2, 4]);
+  });
+
   test("ignores built expressions and exprs outside a RuleGroup", () => {
     const diags = promqlLiteralRule.check(
       ctx(`

package/src/model.ts

@@ -13,6 +13,31 @@
  * docs apply word for word.
  */
 
+import {
+  RECEIVER_INTEGRATION_TYPES,
+  type DiscordConfig,
+  type EmailConfig,
+  type HttpClientConfig,
+  type IncidentioConfig,
+  type JiraConfig,
+  type MattermostConfig,
+  type MSTeamsConfig,
+  type MSTeamsV2Config,
+  type OpsGenieConfig,
+  type PagerDutyConfig,
+  type PushoverConfig,
+  type ReceiverIntegration,
+  type RocketchatConfig,
+  type SlackConfig,
+  type SNSConfig,
+  type TelegramConfig,
+  type TlsConfig,
+  type VictorOpsConfig,
+  type WebexConfig,
+  type WebhookConfig,
+  type WechatConfig,
+} from "./integrations";
+
 /** Labels or annotations: string keys to string values. */
 export type LabelSet = Record<string, string>;
 
@@ -78,112 +103,31 @@ export function ruleName(rule: RuleConfig): string {
 
 // ── 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;
-}
+export * from "./integrations";
 
 /** One entry under `receivers:`. */
 export interface ReceiverConfig {
   name: string;
-  webhook_configs?: WebhookConfig[];
+  /** Labels on the receiver, exposed to notification templates. */
+  labels?: LabelSet;
+  discord_configs?: DiscordConfig[];
   email_configs?: EmailConfig[];
-  slack_configs?: SlackConfig[];
+  incidentio_configs?: IncidentioConfig[];
   pagerduty_configs?: PagerDutyConfig[];
+  slack_configs?: SlackConfig[];
+  webhook_configs?: WebhookConfig[];
+  opsgenie_configs?: OpsGenieConfig[];
+  wechat_configs?: WechatConfig[];
+  pushover_configs?: PushoverConfig[];
+  victorops_configs?: VictorOpsConfig[];
+  sns_configs?: SNSConfig[];
+  telegram_configs?: TelegramConfig[];
+  webex_configs?: WebexConfig[];
+  msteams_configs?: MSTeamsConfig[];
+  msteamsv2_configs?: MSTeamsV2Config[];
+  jira_configs?: JiraConfig[];
+  rocketchat_configs?: RocketchatConfig[];
+  mattermost_configs?: MattermostConfig[];
 }
 
 /** A route in the routing tree. The top-level `route:` is the root. */
@@ -198,11 +142,18 @@ export interface RouteConfig {
   repeat_interval?: string;
   mute_time_intervals?: string[];
   active_time_intervals?: string[];
+  /**
+   * Labels on the route, inherited by child routes and exposed to
+   * notification templates as `routeLabels`. Values may be Go templates.
+   */
+  labels?: LabelSet;
   routes?: RouteConfig[];
 }
 
 /** One entry under `inhibit_rules:`. */
 export interface InhibitRuleConfig {
+  /** A name for the rule, shown in Alertmanager's logs and metrics. */
+  name?: string;
   source_matchers?: string[];
   target_matchers?: string[];
   /** Labels that must be equal on source and target for the inhibition to apply. */
@@ -235,12 +186,18 @@ export interface TimeIntervalConfig {
   time_intervals: TimePeriodConfig[];
 }
 
-/** `global:` settings. */
+/**
+ * `global:` settings: defaults the receivers fall back to. Credentials with
+ * a `*_file` sibling are best set through it; PROM001 flags a literal.
+ */
 export interface AlertmanagerGlobalConfig {
+  /** How long an alert that stops being updated stays firing. */
   resolve_timeout?: string;
+  http_config?: HttpClientConfig;
+  jira_api_url?: string;
   smtp_from?: string;
-  smtp_smarthost?: string;
   smtp_hello?: string;
+  smtp_smarthost?: string;
   smtp_auth_username?: string;
   smtp_auth_password?: string;
   smtp_auth_password_file?: string;
@@ -248,10 +205,93 @@ export interface AlertmanagerGlobalConfig {
   smtp_auth_secret_file?: string;
   smtp_auth_identity?: string;
   smtp_require_tls?: boolean;
+  smtp_tls_config?: TlsConfig;
+  smtp_force_implicit_tls?: boolean;
   slack_api_url?: string;
   slack_api_url_file?: string;
+  slack_app_token?: string;
+  slack_app_token_file?: string;
+  slack_app_url?: string;
   pagerduty_url?: string;
-  http_config?: HttpClientConfig;
+  opsgenie_api_url?: string;
+  opsgenie_api_key?: string;
+  opsgenie_api_key_file?: string;
+  wechat_api_url?: string;
+  wechat_api_secret?: string;
+  wechat_api_secret_file?: string;
+  wechat_api_corp_id?: string;
+  victorops_api_url?: string;
+  victorops_api_key?: string;
+  victorops_api_key_file?: string;
+  telegram_api_url?: string;
+  telegram_bot_token?: string;
+  telegram_bot_token_file?: string;
+  webex_api_url?: string;
+  rocketchat_api_url?: string;
+  rocketchat_token?: string;
+  rocketchat_token_file?: string;
+  rocketchat_token_id?: string;
+  rocketchat_token_id_file?: string;
+  mattermost_webhook_url?: string;
+  mattermost_webhook_url_file?: string;
+}
+
+/** Every `global:` field, as a list, for code that reads a parsed file. */
+export const ALERTMANAGER_GLOBAL_FIELDS = Object.freeze(Object.keys({
+  resolve_timeout: true,
+  http_config: true,
+  jira_api_url: true,
+  smtp_from: true,
+  smtp_hello: true,
+  smtp_smarthost: true,
+  smtp_auth_username: true,
+  smtp_auth_password: true,
+  smtp_auth_password_file: true,
+  smtp_auth_secret: true,
+  smtp_auth_secret_file: true,
+  smtp_auth_identity: true,
+  smtp_require_tls: true,
+  smtp_tls_config: true,
+  smtp_force_implicit_tls: true,
+  slack_api_url: true,
+  slack_api_url_file: true,
+  slack_app_token: true,
+  slack_app_token_file: true,
+  slack_app_url: true,
+  pagerduty_url: true,
+  opsgenie_api_url: true,
+  opsgenie_api_key: true,
+  opsgenie_api_key_file: true,
+  wechat_api_url: true,
+  wechat_api_secret: true,
+  wechat_api_secret_file: true,
+  wechat_api_corp_id: true,
+  victorops_api_url: true,
+  victorops_api_key: true,
+  victorops_api_key_file: true,
+  telegram_api_url: true,
+  telegram_bot_token: true,
+  telegram_bot_token_file: true,
+  webex_api_url: true,
+  rocketchat_api_url: true,
+  rocketchat_token: true,
+  rocketchat_token_file: true,
+  rocketchat_token_id: true,
+  rocketchat_token_id_file: true,
+  mattermost_webhook_url: true,
+  mattermost_webhook_url_file: true,
+} satisfies Record<keyof AlertmanagerGlobalConfig, true>)) as readonly (keyof AlertmanagerGlobalConfig)[];
+
+/** `tracing:` settings: where Alertmanager sends its own traces. */
+export interface AlertmanagerTracingConfig {
+  client_type?: "grpc" | "http";
+  endpoint?: string;
+  sampling_fraction?: number;
+  insecure?: boolean;
+  headers?: Record<string, string>;
+  compression?: string;
+  timeout?: string;
+  tls_config?: TlsConfig;
 }
 
 /** A whole `alertmanager.yml`, the file `amtool check-config` reads. */
@@ -262,19 +302,27 @@ export interface AlertmanagerConfig {
   inhibit_rules?: InhibitRuleConfig[];
   receivers?: ReceiverConfig[];
   time_intervals?: TimeIntervalConfig[];
+  tracing?: AlertmanagerTracingConfig;
 }
 
-/** The four receiver integrations this lexicon types. */
-export const RECEIVER_INTEGRATIONS = ["webhook_configs", "email_configs", "slack_configs", "pagerduty_configs"] as const;
+/** The receiver integrations, every one Alertmanager defines. */
+export const RECEIVER_INTEGRATIONS = Object.keys(RECEIVER_INTEGRATION_TYPES) as readonly ReceiverIntegration[];
 
 /** 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;
+  const v = value as Record<string, unknown>;
+  const groups = v.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),
-  );
+  // Grafana's alerting provisioning files also hold `groups:` of named rule lists. Prometheus reads rule
+  // files strictly (unknown keys are errors), so `apiVersion`, a group `folder` or a rule's `data` means Grafana.
+  if ("apiVersion" in v) return false;
+  return groups.every((g) => {
+    if (typeof g !== "object" || g === null) return false;
+    const group = g as Record<string, unknown>;
+    if (typeof group.name !== "string" || !Array.isArray(group.rules) || "folder" in group) return false;
+    return !group.rules.some((r) => typeof r === "object" && r !== null && "data" in r);
+  });
 }
 
 /** True when a parsed document has the shape of an `alertmanager.yml`. */

package/src/plugin.ts

@@ -9,6 +9,9 @@ import { prometheusAuditCatalog } from "./lint/audit-catalog";
 import { completions } from "./lsp/completions";
 import { hover } from "./lsp/hover";
 import { detectTemplate } from "./detect";
+import { PrometheusParser } from "./import/parser";
+import { PrometheusGenerator } from "./import/generator";
+import { ruleGroupsImporter } from "./import/embedded";
 import { initTemplates } from "./init-templates";
 import { prometheusSkills } from "./skill-defs";
 import { CATALOG } from "./catalog";
@@ -110,6 +113,18 @@ export const prometheusPlugin: LexiconPlugin = {
     return detectTemplate(data);
   },
 
+  templateParser() {
+    return new PrometheusParser();
+  },
+
+  templateGenerator() {
+    return new PrometheusGenerator();
+  },
+
+  embeddedImporters() {
+    return [ruleGroupsImporter];
+  },
+
   initTemplates(template?: string) {
     return initTemplates(template);
   },

package/src/skills/chant-prometheus-alertmanager.md

@@ -47,6 +47,10 @@ export const pageMutesTicket = new InhibitRule({
 });
 ```
 
+## Starting from an existing alertmanager.yml
+
+Import it rather than retyping it: `chant import alertmanager.yml --output src` (with `--lexicon prometheus` outside a chant project). The importer writes `receivers.ts`, `time-intervals.ts`, `routes.ts` (the root `Route`, children as `RouteProps` that reference receivers and time intervals by variable), `inhibit-rules.ts` and `settings.ts`. `*_file` paths and Go templates are kept as written; a literal credential is imported as found and PROM001 reports it, so offer to move it to the `*_file` field. Every integration comes back typed (`OpsGenieConfig[]`, `MSTeamsV2Config[]`, ...); a receiver or `global` key Alertmanager doesn't define is spread in from an untyped const, with a warning. `match`/`match_re` and the top-level `mute_time_intervals` come back in their current spelling (`matchers`, `time_intervals`), and `chant import` prints a warning for each.
+
 ## What the checks hold you to
 
 - One root route (the `Route` no other route nests), with a receiver and no matchers (PROM205).

package/src/skills/chant-prometheus.md

@@ -15,6 +15,17 @@ The prometheus lexicon (`@intentius/chant-lexicon-prometheus`) types Prometheus
 export default { lexicons: ["prometheus"] };
 ```
 
+## Starting from an existing rule file
+
+When the user already has a rule file, import it rather than retyping it:
+
+```bash
+chant import rules.yml --output src          # add --lexicon prometheus outside a chant project
+chant build src --lexicon prometheus -o rules.yml   # the same groups back
+```
+
+The importer writes `rules.ts` (per group, a `Rule[]` const of plain objects and a `RuleGroup`) and `slos.ts` for any group an `Slo()` built, as the `Slo` call. Multi-line expressions become template literals and Go templates in annotations stay as written. Read the warnings `chant import` prints: they name any field Prometheus doesn't define, which is not carried.
+
 ## Declaring a group
 
 A group takes the rule file's own keys (`name`, `interval`, `query_offset`, `limit`, `labels`, `rules`). Rules are plain objects: `record` + `expr` for a recording rule, `alert` + `expr` (+ `for`, `keep_firing_for`, `labels`, `annotations`) for an alerting rule.