@intentius/chant-lexicon-prometheus 0.102.0 → 0.104.1

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

@@ -0,0 +1,18 @@
+/**
+ * PROM224: An inhibit rule matches one alert as source and target, with no equal
+ *
+ * With no equal, any alert matching the source mutes every alert matching the
+ * target. When one alert can match both, alerts of that kind mute each other.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { alertmanagerDiagnostics } from "./prom-helpers";
+
+export const prom224: PostSynthCheck = {
+  id: "PROM224",
+  description: "An inhibit rule matches one alert as source and target, with no equal",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return alertmanagerDiagnostics(ctx, "PROM224");
+  },
+};

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

@@ -0,0 +1,157 @@
+/**
+ * PROM301 (#3364): rule selectors under a connector namespace against what
+ * the build's collector configs emit.
+ */
+import { describe, expect, test } from "vitest";
+import type { Declarable } from "@intentius/chant/declarable";
+import { makePostSynthCtx, makePostSynthCtxFromFiles } from "@intentius/chant-test-utils";
+import { PrometheusExporter, ServiceGraphConnector, SpanMetricsConnector } from "@intentius/chant-lexicon-otel/components/index";
+import { genAiMetrics, genAiPipeline, type GenAiMetricsOptions } from "@intentius/chant-lexicon-otel/genai";
+import { collectorYaml } from "@intentius/chant-lexicon-otel/collector";
+import { prom301 } from "./prom301";
+import { emitYaml } from "../../build";
+import { ruleGroupConfig } from "../../rules";
+import { GenAiRules, type GenAiAlerting, type GenAiPrice } from "../../composites/genai";
+import { Slo } from "../../composites/slo";
+import type { RuleGroupConfig } from "../../model";
+
+const entities = (...list: Declarable[]) => new Map(list.map((e, i) => [`e${i}`, e] as [string, Declarable]));
+
+/** A rule file of one recording rule per expression. */
+function rules(...exprs: string[]): string {
+  return JSON.stringify({ groups: [{ name: "g", rules: exprs.map((expr, i) => ({ record: `job:r${i}:rate5m`, expr })) }] });
+}
+
+/** PROM301's messages for a rule file, with the collector declared as otel entities in the same build. */
+function found(text: string, ...collector: Declarable[]): string[] {
+  return prom301.check(makePostSynthCtx("prometheus", text, entities(...collector))).map((d) => d.message);
+}
+
+describe("PROM301", () => {
+  test("a rule reading traces_span_metrics_calls_total with no spanmetrics connector of that namespace is reported", () => {
+    const msgs = found(rules("sum by (service_name) (rate(traces_span_metrics_calls_total[5m]))"), new SpanMetricsConnector({ namespace: "shop" }));
+    expect(msgs).toEqual(["rule g/job:r0:rate5m reads traces_span_metrics_calls_total, which no collector config in the build emits under traces_span_metrics"]);
+  });
+
+  test("the names a declared connector emits pass, a misspelt one under its namespace does not", () => {
+    const shop = new SpanMetricsConnector({ namespace: "shop", histogram: { unit: "s" } });
+    expect(found(rules("sum by (service_name) (rate(shop_calls_total[5m]))", "histogram_quantile(0.9, sum by (le) (rate(shop_duration_seconds_bucket[5m])))"), shop)).toEqual([]);
+    expect(found(rules("sum(rate(shop_call_total[5m]))"), shop)).toEqual([
+      "rule g/job:r0:rate5m reads shop_call_total, which no collector config in the build emits under shop",
+    ]);
+    // A duration histogram in ms, read as seconds.
+    expect(found(rules("sum(rate(traces_span_metrics_duration_seconds_count[5m]))"), new SpanMetricsConnector({}))).toHaveLength(1);
+  });
+
+  test("a by (...) label that is not a declared dimension", () => {
+    const spans = new SpanMetricsConnector({ dimensions: [{ name: "http.route" }] });
+    expect(found(rules("sum by (service_name, http_route, job) (rate(traces_span_metrics_calls_total[5m]))"), spans)).toEqual([]);
+    expect(found(rules("sum by (http_method) (rate(traces_span_metrics_calls_total[5m]))"), spans)).toEqual([
+      "rule g/job:r0:rate5m groups traces_span_metrics_calls_total by http_method, which is not a dimension the collector config declares for it",
+    ]);
+    // le belongs to the _bucket series only.
+    expect(found(rules("sum by (le) (rate(traces_span_metrics_duration_milliseconds_count[5m]))"), spans)).toHaveLength(1);
+    // label_replace writes a label of its own, so the aggregation over it is not checked.
+    expect(found(rules('sum by (route) (label_replace(rate(traces_span_metrics_calls_total[5m]), "route", "$1", "http_route", "(.*)"))'), spans)).toEqual([]);
+  });
+
+  test("an exporter that copies every resource attribute leaves the labels open", () => {
+    const spans = new SpanMetricsConnector({});
+    const exporter = new PrometheusExporter({ endpoint: "0.0.0.0:8889", resource_to_telemetry_conversion: { enabled: true } });
+    expect(found(rules("sum by (k8s_namespace_name) (rate(traces_span_metrics_calls_total[5m]))"), spans, exporter)).toEqual([]);
+  });
+
+  test("the exporter's namespace moves every name", () => {
+    const spans = new SpanMetricsConnector({});
+    const exporter = new PrometheusExporter({ endpoint: "0.0.0.0:8889", namespace: "otel" });
+    expect(found(rules("sum(rate(otel_traces_span_metrics_calls_total[5m]))"), spans, exporter)).toEqual([]);
+    expect(found(rules("sum(rate(otel_traces_span_metrics_call_total[5m]))"), spans, exporter)).toHaveLength(1);
+  });
+
+  test("servicegraph names and labels", () => {
+    const graph = new ServiceGraphConnector({ dimensions: ["http.method"] });
+    expect(found(rules("sum by (client, server, client_http_method) (rate(traces_service_graph_request_total[5m]))"), graph)).toEqual([]);
+    expect(found(rules("sum by (client) (rate(traces_service_graph_request_duration_seconds_count[5m]))"), graph)).toHaveLength(1);
+    expect(found(rules("sum by (peer) (rate(traces_service_graph_request_failed_total[5m]))"), graph)).toHaveLength(1);
+  });
+
+  test("silent for names outside every namespace, and with no collector config in the build", () => {
+    expect(found(rules("sum by (job) (rate(http_requests_total[5m]))"), new SpanMetricsConnector({}))).toEqual([]);
+    expect(found(rules("sum by (nope) (rate(traces_span_metrics_calls_totl[5m]))"))).toEqual([]);
+  });
+
+  test("reads a collector config from the output too, as in a ConfigMap or a multi-lexicon context", () => {
+    const yaml = collectorYaml(genAiPipeline({ namespace: "shop" }));
+    const ctx = makePostSynthCtxFromFiles("prometheus", { "collector.yaml": yaml }, rules("sum(rate(traces_span_metrics_calls_total[5m]))"));
+    expect(prom301.check(ctx)).toHaveLength(1);
+  });
+});
+
+describe("PROM301 reads renamed connector types as the built-ins they name", () => {
+  const config = (connectors: string) => `receivers:
+  otlp: {}
+exporters:
+  prometheus:
+    endpoint: 0.0.0.0:8889
+connectors:
+${connectors}
+service:
+  pipelines:
+    traces:
+      receivers: [otlp]
+      exporters: [debug]
+`;
+  const ctx = (yaml: string, text: string) => makePostSynthCtxFromFiles("prometheus", { "collector.yaml": yaml }, text);
+
+  test("span_metrics, service_graph and signal_to_metrics", () => {
+    const yaml = config(`  span_metrics/shop:
+    namespace: shop
+  service_graph: {}
+  signal_to_metrics/genai_client:
+    spans:
+      - name: gen_ai.client.operation.duration
+        unit: s
+        attributes: [{ key: gen_ai.operation.name }]
+        histogram: { buckets: [1] }
+`);
+    const read = rules(
+      "sum by (service_name) (rate(shop_calls_total[5m]))",
+      "sum by (client) (rate(traces_service_graph_request_total[5m]))",
+      "sum by (gen_ai_operation_name, le) (rate(gen_ai_client_operation_duration_seconds_bucket[5m]))",
+    );
+    expect(prom301.check(ctx(yaml, read))).toEqual([]);
+    expect(prom301.check(ctx(yaml, rules("sum(rate(shop_call_total[5m]))", "sum(rate(gen_ai_client_operation_seconds_count[5m]))"))).map((d) => d.entity)).toEqual([
+      "g/job:r0:rate5m",
+      "g/job:r1:rate5m",
+    ]);
+  });
+});
+
+describe("PROM301 on the lexicon's own rules", () => {
+  const groupYaml = (group: RuleGroupConfig) => emitYaml({ groups: [group] });
+  const prices: GenAiPrice[] = [{ provider: "anthropic", model: "m1", inputPerMTok: 3, outputPerMTok: 15, currency: "USD", source: "https://example.com", asOf: "2026-09-29" }];
+  const alerts: GenAiAlerting = { errorRatio: true, latency: true, toolErrorRatio: true, budgets: [{ amount: 5, currency: "USD", per: "hour" }] };
+
+  test.each([
+    ["spans", {}],
+    ["derived client metrics", { clientMetrics: "derive" }],
+    ["provider dimensions and a namespace", { providerDimensions: true, namespace: "ai" }],
+  ] as Array<[string, GenAiMetricsOptions]>)("GenAiRules over genAiPipeline with %s, with and without its alerts", (_label, options) => {
+    const collector = genAiPipeline({ ...options, metricExporters: [new PrometheusExporter({ endpoint: "0.0.0.0:8889" })] });
+    const genAi = genAiMetrics(options);
+    for (const props of [{ genAi, prices }, { genAi, prices, alerts }]) {
+      expect(found(groupYaml(ruleGroupConfig(GenAiRules(props).rules)), ...collector)).toEqual([]);
+    }
+  });
+
+  test("Slo over the default spanmetrics connector", () => {
+    const calls = "traces_span_metrics_calls_total";
+    const slo = Slo({
+      name: "checkout",
+      objective: 0.999,
+      window: "30d",
+      sli: { errors: `sum(rate(${calls}{span_name="checkout",status_code="STATUS_CODE_ERROR"}[{{window}}]))`, total: `sum(rate(${calls}{span_name="checkout"}[{{window}}]))` },
+    });
+    expect(found(groupYaml(ruleGroupConfig(slo.rules)), new SpanMetricsConnector({}))).toEqual([]);
+  });
+});

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

@@ -0,0 +1,23 @@
+/**
+ * PROM301: A rule reads a connector metric no collector in the build emits
+ *
+ * For each selector in a rule whose name falls under a namespace the build's
+ * spanmetrics, servicegraph or GenAI connectors own (spanmetrics' and
+ * servicegraph's defaults included), reports a name no collector config in
+ * the build emits, and a by (...) label that is not a dimension the config
+ * declares for the metrics aggregated. Silent for names outside those
+ * namespaces, and when the build has no collector config. See
+ * ../../collector-metrics.ts.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { collectorMetricDiagnostics } from "./prom-helpers";
+
+export const prom301: PostSynthCheck = {
+  id: "PROM301",
+  description: "A rule reads a connector metric no collector in the build emits",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return collectorMetricDiagnostics(ctx);
+  },
+};

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

@@ -1,5 +1,6 @@
 import * as ts from "typescript";
 import type { LintRule, LintDiagnostic, LintContext } from "@intentius/chant/lint/rule";
+import { SLACK_APP_URL } from "../../validate-integrations";
 import { calleeName, constInitializers, CREDENTIAL_CLASS, literalText, position, propertyName, resolveConst } from "./prom-ast";
 
 /**
@@ -89,6 +90,9 @@ export const literalCredentialRule: LintRule = {
       if (only && integration !== undefined && integration !== only) return;
       const text = literalText(init);
       if (text === undefined || text === "") return;
+      // A Slack bot posts to the public chat.postMessage endpoint with its token
+      // in http_config, and update_message needs exactly that api_url (PROM210).
+      if (key === "api_url" && text === SLACK_APP_URL) return;
       diagnostics.push({
         ruleId: "PROM001",
         severity: "error",

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

@@ -45,6 +45,22 @@ describe("PROM001 literal credential", () => {
     expect(diags).toEqual([]);
   });
 
+  test("accepts Slack's bot endpoint as api_url, which update_message needs", () => {
+    const diags = literalCredentialRule.check(
+      ctx(`
+        new Receiver({
+          name: "chat",
+          slack_configs: [{
+            api_url: "https://slack.com/api/chat.postMessage",
+            update_message: true,
+            http_config: { authorization: { credentials_file: "/etc/slack-bot-token" } },
+          }],
+        });
+      `),
+    );
+    expect(diags).toEqual([]);
+  });
+
   test("follows values lifted into named consts, shorthand props and spreads", () => {
     const diags = literalCredentialRule.check(
       ctx(`

package/src/plugin.test.ts

@@ -38,6 +38,21 @@ describe("prometheus plugin", () => {
       "PROM208",
       "PROM209",
       "PROM210",
+      "PROM211",
+      "PROM212",
+      "PROM213",
+      "PROM214",
+      "PROM215",
+      "PROM216",
+      "PROM217",
+      "PROM218",
+      "PROM219",
+      "PROM220",
+      "PROM221",
+      "PROM222",
+      "PROM223",
+      "PROM224",
+      "PROM301",
     ]);
   });
 
@@ -46,6 +61,13 @@ describe("prometheus plugin", () => {
     expect(Object.keys(prometheusAuditCatalog).sort()).toEqual([...ids].sort());
   });
 
+  it("leaves PROM212 out of the recommended preset, and has it in all (#3363)", () => {
+    const presets = prometheusPlugin.lintPresets!();
+    expect(presets.all).toContain("PROM212");
+    expect(presets.recommended).not.toContain("PROM212");
+    expect(presets.all.filter((id) => !presets.recommended.includes(id))).toEqual(["PROM212"]);
+  });
+
   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);

package/src/plugin.ts

@@ -5,7 +5,7 @@ import { createDiffTool } from "@intentius/chant/lexicon-plugin-helpers";
 import { prometheusSerializer } from "./serializer";
 import { rules } from "./lint/rules";
 import { postSynthChecks } from "./lint/post-synth";
-import { prometheusAuditCatalog } from "./lint/audit-catalog";
+import { OPT_IN_CHECKS, prometheusAuditCatalog } from "./lint/audit-catalog";
 import { completions } from "./lsp/completions";
 import { hover } from "./lsp/hover";
 import { detectTemplate } from "./detect";
@@ -89,6 +89,17 @@ export const prometheusPlugin: LexiconPlugin = {
     return prometheusAuditCatalog;
   },
 
+  /**
+   * `recommended` (what `chant build` reports by default) is every check but
+   * the opt-in ones; `all` adds them. A project turns one on with
+   * `lint.presets: { prometheus: "all" }`, or by naming it in `lint.rules`
+   * (`{ PROM212: "warning" }`), which keeps a check whatever the preset.
+   */
+  lintPresets() {
+    const all = Object.keys(prometheusAuditCatalog);
+    return { recommended: all.filter((id) => !OPT_IN_CHECKS.has(id)), all };
+  },
+
   skills: prometheusSkills,
 
   composites() {

package/src/promql-analysis.ts

@@ -0,0 +1,365 @@
+/**
+ * Reading a parsed PromQL expression: the selectors it reads, the labels its
+ * result keeps, and whether it filters with a comparison. The rule-file
+ * checks PROM211-PROM219 (./validate-config.ts) are built on these.
+ *
+ * The tree is the one `checkPromql` (./promql.ts) parses with
+ * `@prometheus-io/lezer-promql`. Every function here returns nothing for an
+ * expression that does not parse; PROM104 reports that.
+ */
+
+import { parser } from "@prometheus-io/lezer-promql";
+import type { MatchOp } from "./matchers";
+
+type SyntaxNode = ReturnType<typeof parser.parse>["topNode"];
+
+/** The expression under the tree's `PromQL` root, or undefined when it does not parse. */
+export function parsePromql(expr: string): SyntaxNode | undefined {
+  if (typeof expr !== "string" || expr.trim() === "") return undefined;
+  const tree = parser.parse(expr);
+  let broken = false;
+  tree.iterate({
+    enter: (n) => {
+      if (n.type.isError) broken = true;
+      return broken ? false : undefined;
+    },
+  });
+  return broken ? undefined : (tree.topNode.firstChild ?? undefined);
+}
+
+function text(n: SyntaxNode, src: string): string {
+  return src.slice(n.from, n.to);
+}
+
+/** The value of a PromQL string literal: double- or single-quoted with escapes, or a raw backtick string. */
+export function stringValue(literal: string): string {
+  if (literal.startsWith("`")) return literal.slice(1, -1);
+  const body = literal.slice(1, -1);
+  try {
+    return JSON.parse(`"${literal.startsWith("'") ? body.replace(/\\'/g, "'").replace(/"/g, '\\"') : body}"`) as string;
+  } catch {
+    return body;
+  }
+}
+
+function children(n: SyntaxNode): SyntaxNode[] {
+  const out: SyntaxNode[] = [];
+  for (let c = n.firstChild; c; c = c.nextSibling) out.push(c);
+  return out;
+}
+
+/** The arguments of a function call or aggregation body, without the brackets and commas. */
+function args(body: SyntaxNode | null): SyntaxNode[] {
+  return body ? children(body).filter((c) => c.name !== "(" && c.name !== ")" && c.name !== ",") : [];
+}
+
+function unwrap(n: SyntaxNode): SyntaxNode {
+  let cur = n;
+  while (cur.name === "ParenExpr" && cur.firstChild) cur = children(cur).find((c) => c.name !== "(" && c.name !== ")") ?? cur;
+  return cur;
+}
+
+export interface SelectorMatcher {
+  name: string;
+  op: MatchOp;
+  value: string;
+}
+
+/** One vector selector in an expression. */
+export interface Selector {
+  /** The metric name, from the identifier or a `__name__="..."` matcher; undefined when neither names one. */
+  name?: string;
+  matchers: SelectorMatcher[];
+  /** The selector as written. */
+  text: string;
+  /** The functions it sits inside, innermost first, e.g. `["rate", "sum"]` for `sum(rate(x[5m]))`. */
+  within: string[];
+}
+
+function selectorOf(n: SyntaxNode, src: string, within: string[]): Selector {
+  const matchers: SelectorMatcher[] = [];
+  const list = n.getChild("LabelMatchers");
+  for (const c of list ? children(list) : []) {
+    if (c.name !== "UnquotedLabelMatcher" && c.name !== "QuotedLabelMatcher") continue;
+    const label = c.getChild("LabelName") ?? c.getChild("QuotedLabelName");
+    const op = c.getChild("MatchOp");
+    const value = c.getChild("StringLiteral");
+    if (!label || !op || !value) continue;
+    const name = label.name === "QuotedLabelName" ? stringValue(text(label, src)) : text(label, src);
+    matchers.push({ name, op: text(op, src) as MatchOp, value: stringValue(text(value, src)) });
+  }
+  const ident = n.getChild("Identifier");
+  const byName = matchers.find((m) => m.name === "__name__" && m.op === "=");
+  const name = ident ? text(ident, src) : byName?.value;
+  return { name, matchers, text: text(n, src), within };
+}
+
+/** The name of a function call or aggregation node, e.g. `rate` or `sum`. */
+function callName(n: SyntaxNode, src: string): string | undefined {
+  if (n.name === "FunctionCall") {
+    const id = n.getChild("FunctionIdentifier");
+    return id ? text(id, src) : undefined;
+  }
+  if (n.name === "AggregateExpr") {
+    const op = n.getChild("AggregateOp");
+    return op ? text(op, src) : undefined;
+  }
+  return undefined;
+}
+
+/** Every vector selector in the expression, with the functions around it. */
+export function selectors(expr: string): Selector[] {
+  const top = parsePromql(expr);
+  if (!top) return [];
+  const out: Selector[] = [];
+  const walk = (n: SyntaxNode, within: string[]) => {
+    if (n.name === "VectorSelector") {
+      out.push(selectorOf(n, expr, within));
+      return;
+    }
+    const fn = callName(n, expr);
+    const inner = fn ? [fn, ...within] : within;
+    for (const c of children(n)) walk(c, inner);
+  };
+  walk(top, []);
+  return out;
+}
+
+const COMPARISON = new Set(["Gtr", "Lss", "Gte", "Lte", "Eql", "Neq"]);
+
+function binaryParts(n: SyntaxNode): { lhs: SyntaxNode; op: SyntaxNode; rhs: SyntaxNode; bool: boolean; modifier?: SyntaxNode } {
+  const parts = children(n);
+  return {
+    lhs: parts[0],
+    op: parts[1],
+    rhs: parts[parts.length - 1],
+    bool: parts.some((p) => p.name === "BoolModifier"),
+    modifier: parts.find((p) => p.name === "MatchingModifierClause"),
+  };
+}
+
+/** Functions whose result is itself a condition: they return a series only when something is missing. */
+const CONDITION_FUNCTIONS = new Set(["absent", "absent_over_time"]);
+
+/**
+ * Whether the expression filters its result: a comparison without `bool`,
+ * `absent()`/`absent_over_time()`, or `unless`, anywhere a series can pass
+ * through to the result. An expression without one returns every series it
+ * reads, so an alert on it fires for all of them (pint alerts/comparison).
+ * `or` needs a condition on both sides, since either side alone reaches the
+ * result.
+ */
+export function hasCondition(expr: string): boolean | undefined {
+  const top = parsePromql(expr);
+  if (!top) return undefined;
+  const walk = (raw: SyntaxNode): boolean => {
+    const n = unwrap(raw);
+    switch (n.name) {
+      case "BinaryExpr": {
+        const { lhs, op, rhs, bool } = binaryParts(n);
+        if (COMPARISON.has(op.name)) return !bool || walk(lhs) || walk(rhs);
+        if (op.name === "Unless") return true;
+        if (op.name === "Or") return walk(lhs) && walk(rhs);
+        return walk(lhs) || walk(rhs);
+      }
+      case "FunctionCall": {
+        const fn = callName(n, expr) ?? "";
+        if (CONDITION_FUNCTIONS.has(fn)) return true;
+        return args(n.getChild("FunctionCallBody")).some(walk);
+      }
+      case "AggregateExpr":
+        return args(n.getChild("FunctionCallBody")).some(walk);
+      case "UnaryExpr":
+      case "OffsetExpr":
+      case "StepInvariantExpr":
+        return children(n).some(walk);
+      case "SubqueryExpr":
+      case "MatrixSelector":
+        return n.firstChild ? walk(n.firstChild) : false;
+      default:
+        return false;
+    }
+  };
+  return walk(top);
+}
+
+/**
+ * The labels an expression's result carries, as far as the expression says:
+ * `{ only }` when it keeps exactly these labels (`sum by (job)`), `{ except }`
+ * when it keeps every label but these (`sum without (instance)`), or
+ * undefined when it keeps whatever the series it reads carry.
+ */
+export type LabelScope = { only: Set<string> } | { except: Set<string> };
+
+const KEEPS_INPUT_LABELS = new Set(["topk", "bottomk", "limitk", "limit_ratio"]);
+const NO_LABELS = new Set(["vector", "time", "scalar", "pi"]);
+
+function grouping(mod: SyntaxNode | null, src: string): { by: boolean; labels: string[] } | undefined {
+  if (!mod) return undefined;
+  const labels = (mod.getChild("GroupingLabels")?.getChildren("LabelName") ?? []).map((l) => text(l, src));
+  return { by: !!mod.getChild("By"), labels };
+}
+
+function minus(scope: LabelScope | undefined, drop: string[]): LabelScope {
+  if (!scope) return { except: new Set(drop) };
+  if ("only" in scope) return { only: new Set([...scope.only].filter((l) => !drop.includes(l))) };
+  return { except: new Set([...scope.except, ...drop]) };
+}
+
+function plus(scope: LabelScope | undefined, add: string[]): LabelScope | undefined {
+  if (!scope) return undefined;
+  if ("only" in scope) return { only: new Set([...scope.only, ...add]) };
+  return { except: new Set([...scope.except].filter((l) => !add.includes(l))) };
+}
+
+/** The labels the expression's result keeps; see {@link LabelScope}. */
+export function resultLabels(expr: string): LabelScope | undefined {
+  const top = parsePromql(expr);
+  if (!top) return undefined;
+  const walk = (raw: SyntaxNode): LabelScope | undefined => {
+    const n = unwrap(raw);
+    switch (n.name) {
+      case "NumberDurationLiteral":
+      case "StringLiteral":
+        return { only: new Set() };
+      case "AggregateExpr": {
+        const op = callName(n, expr) ?? "";
+        const body = args(n.getChild("FunctionCallBody"));
+        const last = body[body.length - 1];
+        const inner = last ? walk(last) : undefined;
+        if (KEEPS_INPUT_LABELS.has(op)) return inner;
+        if (op === "count_values") return undefined;
+        const g = grouping(n.getChild("AggregateModifier"), expr);
+        if (!g) return { only: new Set() };
+        return g.by ? { only: new Set(g.labels) } : minus(inner, g.labels);
+      }
+      case "FunctionCall": {
+        const fn = callName(n, expr) ?? "";
+        if (NO_LABELS.has(fn)) return { only: new Set() };
+        const a = args(n.getChild("FunctionCallBody"));
+        if (fn === "histogram_quantile" || fn === "histogram_fraction") return minus(walk(a[a.length - 1]), ["le"]);
+        if (fn === "label_replace" || fn === "label_join") {
+          const dst = a[1]?.name === "StringLiteral" ? stringValue(text(a[1], expr)) : undefined;
+          return dst === undefined ? undefined : plus(walk(a[0]), [dst]);
+        }
+        if (CONDITION_FUNCTIONS.has(fn)) return undefined;
+        const vector = a.find((x) => x.name !== "NumberDurationLiteral" && x.name !== "StringLiteral");
+        return vector ? walk(vector) : { only: new Set() };
+      }
+      case "BinaryExpr": {
+        const { lhs, op, rhs, modifier } = binaryParts(n);
+        const l = walk(lhs);
+        const r = walk(rhs);
+        const lScalar = unwrap(lhs).name === "NumberDurationLiteral";
+        const rScalar = unwrap(rhs).name === "NumberDurationLiteral";
+        if (lScalar && !rScalar) return r;
+        if (rScalar) return l;
+        if (op.name === "And" || op.name === "Unless") return l;
+        if (op.name === "Or") {
+          if (l && r && "only" in l && "only" in r) return { only: new Set([...l.only, ...r.only]) };
+          return undefined;
+        }
+        if (!modifier) return l;
+        const on = !!modifier.getChild("On");
+        const groupLabels = modifier.getChildren("GroupingLabels").map((g) => g.getChildren("LabelName").map((x) => text(x, expr)));
+        const matching = groupLabels[0] ?? [];
+        const extra = groupLabels[1] ?? [];
+        if (modifier.getChild("GroupLeft")) return plus(l, extra);
+        if (modifier.getChild("GroupRight")) return plus(r, extra);
+        // One-to-one: `on` keeps only the matching labels, `ignoring` drops them.
+        return on ? { only: new Set(matching.filter((x) => !l || ("only" in l ? l.only.has(x) : !l.except.has(x)))) } : minus(l, matching);
+      }
+      case "UnaryExpr":
+      case "OffsetExpr":
+      case "StepInvariantExpr":
+        return walk(children(n).find((c) => c.name !== "UnaryOp" && c.name !== "Offset" && c.name !== "OffsetDurationExpr") ?? n.firstChild!);
+      default:
+        return undefined;
+    }
+  };
+  return walk(top);
+}
+
+/** Whether a label survives a scope. An undefined scope keeps every label. */
+export function keepsLabel(scope: LabelScope | undefined, label: string): boolean {
+  if (!scope) return true;
+  return "only" in scope ? scope.only.has(label) : !scope.except.has(label);
+}
+
+/** One `histogram_quantile` call and what is wrong with its histogram argument. */
+export interface HistogramProblem {
+  call: string;
+  problem: "no-bucket" | "no-le";
+}
+
+/** `histogram_quantile` calls over a selector with no `_bucket` in its name, or an aggregation that drops `le`. */
+export function histogramProblems(expr: string): HistogramProblem[] {
+  const top = parsePromql(expr);
+  if (!top) return [];
+  const out: HistogramProblem[] = [];
+  const walk = (n: SyntaxNode) => {
+    if (n.name === "FunctionCall" && callName(n, expr) === "histogram_quantile") {
+      const a = args(n.getChild("FunctionCallBody"));
+      const histogram = a[1];
+      if (histogram) {
+        const call = text(n, expr);
+        const names = selectors(text(histogram, expr)).flatMap((s) => (s.name ? [s.name] : []));
+        if (names.some((x) => !x.includes("_bucket"))) out.push({ call, problem: "no-bucket" });
+        else if (!keepsLabel(resultLabels(text(histogram, expr)), "le")) out.push({ call, problem: "no-le" });
+      }
+    }
+    for (const c of children(n)) walk(c);
+  };
+  walk(top);
+  return out;
+}
+
+const COUNTER_FUNCTIONS = new Set(["rate", "irate", "increase"]);
+const COUNTER_SUFFIX = /_(total|count|sum|bucket)$/;
+
+/** `rate`, `irate` or `increase` read straight from a named selector whose name does not end in a counter suffix. */
+export function nonCounterRates(expr: string): Array<{ fn: string; name: string }> {
+  return selectors(expr).flatMap((s) => {
+    const fn = s.within[0];
+    if (!fn || !COUNTER_FUNCTIONS.has(fn) || !s.name || COUNTER_SUFFIX.test(s.name)) return [];
+    return [{ fn, name: s.name }];
+  });
+}
+
+const REGEX_META = /[.+*?()[\]{}|\\^$]/;
+
+/** A regex matcher that could be an equality matcher, or that carries anchors Prometheus already adds. */
+export interface RegexProblem {
+  matcher: string;
+  problem: "literal" | "anchored";
+}
+
+/** The `=~` and `!~` matchers in an expression that need no regex, or that are anchored (pint promql/regexp). */
+export function regexProblems(expr: string): RegexProblem[] {
+  const out: RegexProblem[] = [];
+  for (const s of selectors(expr)) {
+    for (const m of s.matchers) {
+      if (m.op !== "=~" && m.op !== "!~") continue;
+      const shown = `${m.name}${m.op}${JSON.stringify(m.value)}`;
+      if (!REGEX_META.test(m.value)) out.push({ matcher: shown, problem: "literal" });
+      else if (m.value.startsWith("^") || (m.value.endsWith("$") && !m.value.endsWith("\\$"))) out.push({ matcher: shown, problem: "anchored" });
+    }
+  }
+  return out;
+}
+
+/** Whether every selector in the expression is read through a `*_over_time` function, so the expression already spans a window. */
+export function readsOnlyOverTime(expr: string): boolean {
+  const all = selectors(expr);
+  return all.length > 0 && all.every((s) => s.within.some((fn) => fn.endsWith("_over_time")));
+}
+
+/** Whether the expression is two conditions joined by `and`: the multi-window form, where the short window does what `for` would. */
+export function isMultiWindow(expr: string): boolean {
+  const top = parsePromql(expr);
+  if (!top) return false;
+  const n = unwrap(top);
+  if (n.name !== "BinaryExpr") return false;
+  const { lhs, op, rhs } = binaryParts(n);
+  return op.name === "And" && hasCondition(text(lhs, expr)) === true && hasCondition(text(rhs, expr)) === true;
+}