@intentius/chant-lexicon-prometheus 0.105.1 → 0.106.3

package/src/index.ts

@@ -2,7 +2,7 @@
 
 // Plugin and serializer
 export { prometheusPlugin } from "./plugin";
-export { prometheusSerializer, ALERTMANAGER_FILE } from "./serializer";
+export { prometheusSerializer, ALERTMANAGER_FILE, PROMETHEUS_FILE } from "./serializer";
 
 // Rule groups
 export {
@@ -50,16 +50,34 @@ export {
   type AlertmanagerSettingsEntity,
 } from "./alertmanager";
 
+// prometheus.yml
+export {
+  PrometheusConfig,
+  ScrapeConfig,
+  PROMETHEUS_CONFIG_TYPE,
+  SCRAPE_CONFIG_TYPE,
+  isPrometheusConfig,
+  isScrapeConfig,
+  isPrometheusConfigEntity,
+  type PrometheusConfigProps,
+  type PrometheusConfigEntity,
+  type ScrapeConfigProps,
+  type ScrapeConfigEntity,
+} from "./prometheus-config";
+
 // The plain-data model, building, YAML and checks
 export * from "./model";
 export {
   buildRuleFile,
   buildAlertmanagerConfig,
+  buildPrometheusConfig,
   ruleFileYaml,
   alertmanagerYaml,
+  prometheusConfigYaml,
   emitYaml,
   type BuiltRuleFile,
   type BuiltAlertmanager,
+  type BuiltPrometheusConfig,
 } from "./build";
 export { isValidDuration, durationMs, formatDuration } from "./duration";
 export { parseMatchers, matcherMatches, matcher, type Matcher, type MatchOp, type ParsedMatchers } from "./matchers";
@@ -76,7 +94,7 @@ export {
 export { PROMETHEUS_PIN } from "./pin";
 
 // promtool and amtool, when installed
-export { promtoolCheckRules, promtoolTestRules, amtoolCheckConfig, hasTool, type ToolResult } from "./tools";
+export { promtoolCheckRules, promtoolCheckConfig, promtoolTestRules, amtoolCheckConfig, hasTool, type ToolResult } from "./tools";
 
 // Composites
 export {
@@ -84,6 +102,7 @@ export {
   sloMetrics,
   sloPropsProblem,
   sliExprProblem,
+  eventCount,
   DEFAULT_BURN_RATES,
   SLO_WINDOW_PLACEHOLDER,
   type SloProps,

package/src/lint/audit-catalog.ts

@@ -220,6 +220,13 @@ export const prometheusAuditCatalog: Record<string, RuleMeta> = {
     "Inhibit rule matches one alert as source and target, with no equal",
     "List the labels source and target must share under equal (e.g. alertname, cluster), or make the matchers exclusive.",
   ),
+  PROM225: outputRule(
+    "PROM225",
+    "merge-worthy",
+    "correctness",
+    "labeldrop or labelkeep relabel step carries a field it does not take",
+    "Remove source_labels, separator, target_label, modulus and replacement from the step; keep only regex (and action).",
+  ),
   PROM301: outputRule(
     "PROM301",
     "merge-worthy",

package/src/lint/audit-lineage.test.ts

@@ -36,7 +36,7 @@ describe("prometheus audit lineage (#2916, #3136)", () => {
   });
 
   test("rules no upstream tool checks carry no credit", () => {
-    for (const id of ["PROM001", "PROM003", "PROM202", "PROM207", "PROM216", "PROM219", "PROM220", "PROM221", "PROM222", "PROM223", "PROM224", "PROM301"]) {
+    for (const id of ["PROM001", "PROM003", "PROM202", "PROM207", "PROM216", "PROM219", "PROM220", "PROM221", "PROM222", "PROM223", "PROM224", "PROM225", "PROM301"]) {
       expect(prometheusAuditCatalog[id].lineage, id).toBeUndefined();
     }
   });

package/src/lint/audit-lineage.ts

@@ -46,6 +46,8 @@
  * - PROM220-PROM224: check-config accepts insecure_skip_verify, SMTP auth
  *   without TLS, credentials over http://, a repeat_interval under
  *   group_interval, and an inhibit rule without equal.
+ * - PROM225: promtool check config rejects it, but the check reads a built
+ *   prometheus.yml, which no tool above does.
  * - PROM301: no tool here reads a rule file together with the collector
  *   config that produces its metrics.
  */

package/src/lint/post-synth/checks.test.ts

@@ -10,6 +10,7 @@ import { build } from "@intentius/chant/build";
 import { runPostSynthChecks } from "@intentius/chant/lint/post-synth";
 import { genAiMetrics } from "@intentius/chant-lexicon-otel/genai";
 import { postSynthChecks } from "./index";
+import { prom225 } from "./prom225";
 import { OPT_IN_CHECKS } from "../audit-catalog";
 import { prometheusSerializer } from "../../serializer";
 import { emitYaml } from "../../build";
@@ -255,3 +256,36 @@ describe("the lexicon's own rules report none of the checks", () => {
     expect(diags).toEqual([]);
   });
 });
+
+describe("PROM225 labeldrop and labelkeep fields", () => {
+  const prom = (step: Record<string, unknown>) =>
+    JSON.stringify({ scrape_configs: [{ job_name: "j", static_configs: [{ targets: ["a:1"] }], metric_relabel_configs: [step] }] });
+  const run = (text: string) => prom225.check(makePostSynthCtx("prometheus", text));
+
+  test("a labeldrop with only regex reports nothing", () => {
+    expect(run(prom({ action: "labeldrop", regex: "tmp_.*" }))).toEqual([]);
+    expect(run(prom({ action: "replace", source_labels: ["a"], target_label: "b" }))).toEqual([]);
+  });
+
+  test("each foreign field on labeldrop or labelkeep is reported once per step", () => {
+    for (const action of ["labeldrop", "labelkeep"]) {
+      for (const field of ["source_labels", "separator", "target_label", "modulus", "replacement"]) {
+        const diags = run(prom({ action, regex: "x", [field]: field === "modulus" ? 2 : field === "source_labels" ? ["a"] : "v" }));
+        expect(diags.map((d) => d.checkId), `${action} ${field}`).toEqual(["PROM225"]);
+        expect(diags[0].entity).toBe("scrape_configs[0].metric_relabel_configs[0]");
+        expect(diags[0].message).toContain(field);
+      }
+    }
+  });
+
+  test("steps under remote_write and alerting are read too", () => {
+    const text = JSON.stringify({
+      alerting: { alert_relabel_configs: [{ action: "labelkeep", regex: "a", replacement: "$1" }] },
+      remote_write: [{ url: "http://r", write_relabel_configs: [{ action: "labeldrop", regex: "a", separator: ";" }] }],
+    });
+    expect(run(text).map((d) => d.entity)).toEqual([
+      "alerting.alert_relabel_configs[0]",
+      "remote_write[0].write_relabel_configs[0]",
+    ]);
+  });
+});

package/src/lint/post-synth/index.ts

@@ -31,6 +31,7 @@ import { prom221 } from "./prom221";
 import { prom222 } from "./prom222";
 import { prom223 } from "./prom223";
 import { prom224 } from "./prom224";
+import { prom225 } from "./prom225";
 import { prom301 } from "./prom301";
 
 export const postSynthChecks: PostSynthCheck[] = [
@@ -65,5 +66,6 @@ export const postSynthChecks: PostSynthCheck[] = [
   prom222,
   prom223,
   prom224,
+  prom225,
   prom301,
 ];

package/src/lint/post-synth/prom-helpers.ts

@@ -14,6 +14,8 @@ import type { PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lin
 import type { SerializerResult } from "@intentius/chant/serializer";
 import { loadAll } from "js-yaml";
 import { buildCollectorConfigs, collectorMetricIssues, collectorMetrics } from "../../collector-metrics";
+import { looksLikePrometheusConfig, type PrometheusConfigFile } from "../../config-model";
+import { validateRelabelFields } from "../../validate-relabel";
 import { looksLikeAlertmanagerConfig, looksLikeRuleFile, type AlertmanagerConfig, type RuleFileConfig } from "../../model";
 import {
   validateAlertmanagerConfig,
@@ -27,11 +29,12 @@ import {
 export interface FoundDocs {
   ruleFiles: Array<{ source: string; config: RuleFileConfig }>;
   alertmanager: Array<{ source: string; config: AlertmanagerConfig }>;
+  prometheus: Array<{ source: string; config: PrometheusConfigFile }>;
 }
 
 /** Every rule file and Alertmanager config in the output. Parsed with js-yaml rather than `ctx.docs`, which keeps block scalars and flow lists as strings. */
 export function prometheusDocs(ctx: PostSynthContext): FoundDocs {
-  const found: FoundDocs = { ruleFiles: [], alertmanager: [] };
+  const found: FoundDocs = { ruleFiles: [], alertmanager: [], prometheus: [] };
   for (const [lexicon, output] of ctx.outputs) {
     const texts: Array<[string, string]> =
       typeof output === "string"
@@ -48,6 +51,7 @@ export function prometheusDocs(ctx: PostSynthContext): FoundDocs {
       for (const doc of docs) {
         if (looksLikeRuleFile(doc)) found.ruleFiles.push({ source, config: doc });
         else if (looksLikeAlertmanagerConfig(doc)) found.alertmanager.push({ source, config: doc });
+        else if (looksLikePrometheusConfig(doc)) found.prometheus.push({ source, config: doc });
       }
     }
   }
@@ -82,6 +86,11 @@ export function alertmanagerDiagnostics(ctx: PostSynthContext, code: PrometheusI
   );
 }
 
+/** PROM225 across every `prometheus.yml` in the output. */
+export function relabelDiagnostics(ctx: PostSynthContext): PostSynthDiagnostic[] {
+  return prometheusDocs(ctx).prometheus.flatMap(({ source, config }) => validateRelabelFields(config).map((i) => toDiagnostic(i, source)));
+}
+
 /** PROM212 across every rule file in the output. Opt-in: the lexicon's `recommended` lint preset leaves it out (see ../../plugin.ts). */
 export function runbookDiagnostics(ctx: PostSynthContext): PostSynthDiagnostic[] {
   return prometheusDocs(ctx).ruleFiles.flatMap(({ source, config }) => validateRunbookUrls(config).map((i) => toDiagnostic(i, source)));

package/src/lint/post-synth/prom225.ts

@@ -0,0 +1,19 @@
+/**
+ * PROM225: A labeldrop or labelkeep relabel step carries a field it does not take
+ *
+ * Both actions match regex against label names, so source_labels, separator,
+ * target_label, modulus and replacement do nothing, and Prometheus rejects the
+ * file at load. Reads every prometheus.yml in the output.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { relabelDiagnostics } from "./prom-helpers";
+
+export const prom225: PostSynthCheck = {
+  id: "PROM225",
+  description: "A labeldrop or labelkeep relabel step carries a field it does not take",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return relabelDiagnostics(ctx);
+  },
+};

package/src/model.ts

@@ -104,6 +104,7 @@ export function ruleName(rule: RuleConfig): string {
 // ── Alertmanager ────────────────────────────────────────────────────
 
 export * from "./integrations";
+export * from "./config-model";
 
 /** One entry under `receivers:`. */
 export interface ReceiverConfig {

package/src/plugin.test.ts

@@ -52,6 +52,7 @@ describe("prometheus plugin", () => {
       "PROM222",
       "PROM223",
       "PROM224",
+      "PROM225",
       "PROM301",
     ]);
   });

package/src/plugin.ts

@@ -11,7 +11,7 @@ import { hover } from "./lsp/hover";
 import { detectTemplate } from "./detect";
 import { PrometheusParser } from "./import/parser";
 import { PrometheusGenerator } from "./import/generator";
-import { alertmanagerImporter, ruleGroupsImporter } from "./import/embedded";
+import { alertmanagerImporter, prometheusConfigImporter, ruleGroupsImporter } from "./import/embedded";
 import { DEFAULT_TEMPLATE, RULES_TEMPLATE, SLO_STYLE_TEMPLATE, SLO_TEMPLATE } from "./init-templates";
 import { prometheusSkills } from "./skill-defs";
 import { CATALOG } from "./catalog";
@@ -57,6 +57,7 @@ export const prometheusPlugin: LexiconPlugin = {
     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(", "),
@@ -133,7 +134,7 @@ export const prometheusPlugin: LexiconPlugin = {
   },
 
   embeddedImporters() {
-    return [ruleGroupsImporter, alertmanagerImporter];
+    return [ruleGroupsImporter, alertmanagerImporter, prometheusConfigImporter];
   },
 
   // `chant init --lexicon prometheus [--template rules|slo-style|slo]`; see ./init-templates.ts.

package/src/prometheus-config.test.ts

@@ -0,0 +1,230 @@
+/**
+ * `prometheus.yml` as entities: `PrometheusConfig` and `ScrapeConfig` build to
+ * the file, the serializer writes it beside the other files, and
+ * `promtool check config` accepts it when `promtool` is on PATH.
+ *
+ * The import round trip is in import/prometheus-roundtrip.test.ts.
+ */
+
+import { describe, expect, test } from "vitest";
+import { load } from "js-yaml";
+import type { Declarable } from "@intentius/chant/declarable";
+import { buildPrometheusConfig, prometheusConfigYaml } from "./build";
+import { PrometheusConfig, ScrapeConfig, isPrometheusConfig, isScrapeConfig } from "./prometheus-config";
+import { prometheusSerializer, PROMETHEUS_FILE, ALERTMANAGER_FILE } from "./serializer";
+import { Receiver, Route, RuleGroup } from "./index";
+import { hasTool, promtoolCheckConfig } from "./tools";
+import { CATALOG } from "./catalog";
+import { detectTemplate } from "./detect";
+import { PrometheusParser } from "./import/parser";
+import type { SerializerResult } from "@intentius/chant/serializer";
+
+const PROMTOOL = hasTool(process.env.PROMTOOL ?? "promtool");
+
+function entities(record: Record<string, unknown>): Map<string, Declarable> {
+  return new Map(Object.entries(record) as Array<[string, Declarable]>);
+}
+
+/** What terragucci's observability/prometheus.ts emits today. */
+const terragucci = () => ({
+  config: new PrometheusConfig({ global: { scrape_interval: "5s" } }),
+  collector: new ScrapeConfig({ job_name: "otel-collector", static_configs: [{ targets: ["otel-collector:8889"] }] }),
+});
+
+const TERRAGUCCI_YAML = `global:
+  scrape_interval: 5s
+scrape_configs:
+  - job_name: otel-collector
+    static_configs:
+      - targets:
+          - otel-collector:8889
+`;
+
+describe("PrometheusConfig and ScrapeConfig", () => {
+  test("the guards tell the two entities apart", () => {
+    const { config, collector } = terragucci();
+    expect(isPrometheusConfig(config)).toBe(true);
+    expect(isScrapeConfig(config)).toBe(false);
+    expect(isScrapeConfig(collector)).toBe(true);
+    expect(isPrometheusConfig(collector)).toBe(false);
+  });
+
+  test("both are in the catalog", () => {
+    const names = CATALOG.filter((c) => c.file === "prometheus.yml").map((c) => c.className);
+    expect(names.sort()).toEqual(["PrometheusConfig", "ScrapeConfig"]);
+  });
+
+  test("the config terragucci emits today builds to the same text", () => {
+    expect(prometheusConfigYaml(Object.values(terragucci()) as unknown as Declarable[])).toBe(TERRAGUCCI_YAML);
+  });
+
+  test("sections come out in Prometheus's order and scrape jobs are sorted by name", () => {
+    const built = buildPrometheusConfig([
+      new ScrapeConfig({ job_name: "zeta", static_configs: [{ targets: ["z:1"] }] }),
+      new ScrapeConfig({ job_name: "alpha", static_configs: [{ targets: ["a:1"] }] }),
+      new PrometheusConfig({
+        otlp: { promote_resource_attributes: ["service.name"] },
+        rule_files: ["rules/*.yml"],
+        global: { scrape_interval: "15s", external_labels: { cluster: "dev" } },
+        alerting: { alertmanagers: [{ static_configs: [{ targets: ["alertmanager:9093"] }] }] },
+        remote_write: [{ url: "http://mimir:9009/api/v1/push" }],
+      }),
+    ]);
+    expect(Object.keys(built.config)).toEqual(["global", "alerting", "rule_files", "scrape_configs", "remote_write", "otlp"]);
+    expect(built.config.scrape_configs?.map((j) => j.job_name)).toEqual(["alpha", "zeta"]);
+    expect(built.warnings).toEqual([]);
+    expect(built.count).toBe(3);
+  });
+
+  test("scrape jobs written inline in PrometheusConfig are merged with declared ones", () => {
+    const declared = new ScrapeConfig({ job_name: "declared", static_configs: [{ targets: ["d:1"] }] });
+    const built = buildPrometheusConfig([
+      declared,
+      new PrometheusConfig({ scrape_configs: [declared, { job_name: "inline", static_configs: [{ targets: ["i:1"] }] }] }),
+    ]);
+    expect(built.config.scrape_configs?.map((j) => j.job_name)).toEqual(["declared", "inline"]);
+  });
+
+  test("undefined fields are dropped", () => {
+    const yaml = prometheusConfigYaml([new ScrapeConfig({ job_name: "a", scrape_interval: undefined, honor_labels: false })]);
+    expect(load(yaml)).toEqual({ scrape_configs: [{ job_name: "a", honor_labels: false }] });
+  });
+
+  test("a repeated job_name and a second PrometheusConfig are warnings", () => {
+    const built = buildPrometheusConfig([
+      new ScrapeConfig({ job_name: "dup" }),
+      new ScrapeConfig({ job_name: "dup" }),
+      new PrometheusConfig({ global: { scrape_interval: "1s" } }),
+      new PrometheusConfig({ global: { scrape_interval: "2s" } }),
+    ]);
+    expect(built.warnings).toHaveLength(2);
+    expect(built.config.global?.scrape_interval).toBe("1s");
+  });
+
+  test("an unlisted discovery kind is carried as written", () => {
+    const yaml = prometheusConfigYaml([
+      new ScrapeConfig({ job_name: "docker", docker_sd_configs: [{ host: "unix:///var/run/docker.sock" }] }),
+    ]);
+    expect(load(yaml)).toEqual({
+      scrape_configs: [{ job_name: "docker", docker_sd_configs: [{ host: "unix:///var/run/docker.sock" }] }],
+    });
+  });
+});
+
+describe("prometheus serializer with prometheus.yml", () => {
+  test("a build with only scrape configs writes prometheus.yml as the primary output", () => {
+    expect(prometheusSerializer.serialize(entities(terragucci()))).toBe(TERRAGUCCI_YAML);
+  });
+
+  test("a build with no prometheus.yml entities is unchanged", () => {
+    const out = prometheusSerializer.serialize(
+      entities({ g: new RuleGroup({ name: "g", rules: [{ record: "a:b", expr: "sum(up)" }] }) }),
+    );
+    expect(typeof out).toBe("string");
+    expect(out as string).toMatch(/^groups:/);
+  });
+
+  test("with rule groups, prometheus.yml is written beside the rule file", () => {
+    const out = prometheusSerializer.serialize(
+      entities({ ...terragucci(), g: new RuleGroup({ name: "g", rules: [{ record: "a:b", expr: "sum(up)" }] }) }),
+    ) as SerializerResult;
+    expect(out.primary).toMatch(/^groups:/);
+    expect(out.files).toEqual({ [PROMETHEUS_FILE]: TERRAGUCCI_YAML });
+  });
+
+  test("with rule groups and Alertmanager entities, all three files are written", () => {
+    const hook = new Receiver({ name: "hook", webhook_configs: [{ url: "http://hook:8080/" }] });
+    const out = prometheusSerializer.serialize(
+      entities({
+        ...terragucci(),
+        g: new RuleGroup({ name: "g", rules: [{ record: "a:b", expr: "sum(up)" }] }),
+        route: new Route({ receiver: hook }),
+      }),
+    ) as SerializerResult;
+    expect(out.primary).toMatch(/^groups:/);
+    expect(Object.keys(out.files ?? {})).toEqual([PROMETHEUS_FILE, ALERTMANAGER_FILE]);
+  });
+
+  test("with Alertmanager entities only, prometheus.yml is primary and alertmanager.yml beside it", () => {
+    const hook = new Receiver({ name: "hook", webhook_configs: [{ url: "http://hook:8080/" }] });
+    const out = prometheusSerializer.serialize(entities({ ...terragucci(), route: new Route({ receiver: hook }) })) as SerializerResult;
+    expect(out.primary).toBe(TERRAGUCCI_YAML);
+    expect(Object.keys(out.files ?? {})).toEqual([ALERTMANAGER_FILE]);
+  });
+
+  test("warnings travel with the output", () => {
+    const out = prometheusSerializer.serialize(
+      entities({ a: new ScrapeConfig({ job_name: "dup" }), b: new ScrapeConfig({ job_name: "dup" }) }),
+    ) as SerializerResult;
+    expect(out.warnings).toHaveLength(1);
+  });
+});
+
+describe("prometheus.yml detection and parsing", () => {
+  test("a prometheus.yml is a template of this lexicon; a bare global block or a collector config is not", () => {
+    expect(detectTemplate(load(TERRAGUCCI_YAML))).toBe(true);
+    expect(detectTemplate({ global: { scrape_interval: "5s" } })).toBe(true);
+    expect(detectTemplate({ global: { resolve_timeout: "5m" } })).toBe(false);
+    expect(detectTemplate({ receivers: { otlp: {} }, exporters: {} })).toBe(false);
+    expect(detectTemplate({ apiVersion: "v1", kind: "ConfigMap", global: { scrape_interval: "5s" } })).toBe(false);
+  });
+
+  test("the parser names what it does not carry", () => {
+    const ir = new PrometheusParser().parse(`scrape_configs:
+  - job_name: a
+    docker_sd_configs: [{ host: "unix:///x.sock" }]
+  - static_configs: [{ targets: ["x:1"] }]
+bogus: 1
+`);
+    expect(ir.resources[0].type).toBe("Prometheus::Config");
+    expect(ir.warnings).toHaveLength(3);
+    expect(ir.warnings?.join("\n")).toContain("docker_sd_configs");
+    expect(ir.warnings?.join("\n")).toContain("has no job_name");
+    expect(ir.warnings?.join("\n")).toContain('"bogus"');
+  });
+});
+
+describe("promtool check config", () => {
+  test.skipIf(!PROMTOOL)("accepts the config terragucci emits", () => {
+    const r = promtoolCheckConfig(prometheusConfigYaml(Object.values(terragucci()) as unknown as Declarable[]));
+    expect(r.ok, r.output).toBe(true);
+  });
+
+  test.skipIf(!PROMTOOL)("accepts a config using the typed sections", () => {
+    const yaml = prometheusConfigYaml([
+      new PrometheusConfig({
+        global: { scrape_interval: "15s", scrape_timeout: "10s", evaluation_interval: "30s", external_labels: { cluster: "dev" } },
+        alerting: { alertmanagers: [{ scheme: "http", api_version: "v2", static_configs: [{ targets: ["alertmanager:9093"] }] }] },
+        rule_files: ["rules.yml"],
+        remote_write: [
+          {
+            url: "http://mimir:9009/api/v1/push",
+            queue_config: { capacity: 10000 },
+            write_relabel_configs: [{ source_labels: ["__name__"], regex: "debug_.*", action: "drop" }],
+          },
+        ],
+        otlp: { promote_resource_attributes: ["service.name"] },
+      }),
+      new ScrapeConfig({
+        job_name: "app",
+        scrape_interval: "5s",
+        params: { format: ["prometheus"] },
+        static_configs: [{ targets: ["app:8080"], labels: { tier: "web" } }],
+        metric_relabel_configs: [{ source_labels: ["__name__"], regex: "go_.*", action: "drop" }],
+      }),
+      new ScrapeConfig({
+        job_name: "dns",
+        dns_sd_configs: [{ names: ["api.service.internal"], type: "A", port: 9100 }],
+        relabel_configs: [{ source_labels: ["__address__"], target_label: "host" }],
+      }),
+    ]);
+    const r = promtoolCheckConfig(yaml, { "rules.yml": "groups:\n  - name: g\n    rules:\n      - record: a:b\n        expr: sum(up)\n" });
+    expect(r.ok, r.output).toBe(true);
+  });
+
+  test.skipIf(!PROMTOOL)("rejects a config Prometheus rejects", () => {
+    const r = promtoolCheckConfig(prometheusConfigYaml([new ScrapeConfig({ job_name: "bad", scrape_interval: "1s", scrape_timeout: "5s" })]));
+    expect(r.ran).toBe(true);
+    expect(r.ok).toBe(false);
+  });
+});

package/src/prometheus-config.ts

@@ -0,0 +1,71 @@
+/**
+ * `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";
+import type { Declarable } from "@intentius/chant/declarable";
+import type { PrometheusConfigSections, ScrapeJobConfig } from "./model";
+
+export const SCRAPE_CONFIG_TYPE = "Prometheus::Config::ScrapeConfig";
+export const PROMETHEUS_CONFIG_TYPE = "Prometheus::Config::PrometheusConfig";
+
+type Ctor<P, E> = new (props: P) => E;
+
+function entityClass<P, E>(entityType: string, className: string): 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>);
+  };
+  Object.defineProperty(Cls, "name", { value: className });
+  return Cls as unknown as Ctor<P, E>;
+}
+
+// ── ScrapeConfig ────────────────────────────────────────────────────
+
+export type ScrapeConfigProps = ScrapeJobConfig;
+
+export interface ScrapeConfigEntity extends Declarable {
+  readonly props: ScrapeConfigProps;
+}
+
+/**
+ * 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<ScrapeConfigProps, ScrapeConfigEntity>(SCRAPE_CONFIG_TYPE, "ScrapeConfig");
+
+// ── PrometheusConfig ────────────────────────────────────────────────
+
+export interface PrometheusConfigProps extends PrometheusConfigSections {
+  /** Scrape jobs written inline, as plain objects. Merged with the declared `ScrapeConfig`s. */
+  scrape_configs?: Array<ScrapeConfigEntity | ScrapeConfigProps>;
+}
+
+export interface PrometheusConfigEntity extends Declarable {
+  readonly props: PrometheusConfigProps;
+}
+
+/** The sections of `prometheus.yml` other than the scrape jobs. Declare at most one. */
+export const PrometheusConfig = entityClass<PrometheusConfigProps, PrometheusConfigEntity>(PROMETHEUS_CONFIG_TYPE, "PrometheusConfig");
+
+// ── Guards ──────────────────────────────────────────────────────────
+
+function isType<T>(type: string) {
+  return (value: unknown): value is T =>
+    typeof value === "object" && value !== null && (value as Declarable).entityType === type;
+}
+
+export const isScrapeConfig = isType<ScrapeConfigEntity>(SCRAPE_CONFIG_TYPE);
+export const isPrometheusConfig = isType<PrometheusConfigEntity>(PROMETHEUS_CONFIG_TYPE);
+
+/** True for an entity that goes into `prometheus.yml`. */
+export function isPrometheusConfigEntity(value: unknown): boolean {
+  return isScrapeConfig(value) || isPrometheusConfig(value);
+}