@miragon/pulse-analytics-client 0.0.0-bootstrap.0 → 0.21.0

package/dist/promql-parse.test-support.js

@@ -0,0 +1,284 @@
+/**
+ * Test support for the metrics-contract guards — never imported by runtime
+ * code. A parser for the PromQL subset the analytics consumers write (TS
+ * queries, alert rules, Grafana dashboards) into the small AST the label
+ * checker (`promql-labels.test-support.ts`) walks.
+ *
+ * Anything outside the supported subset throws instead of parsing to
+ * something approximate — extend the parser when a new query shape needs it.
+ */
+const LEXEMES = [
+    // A Grafana interval variable is a duration too (`offset $__range`).
+    [
+        "duration",
+        /(?:\d+(?:ms|[smhdwy]))+(?![A-Za-z0-9_])|\$__(?:rate_interval|interval|range)(?![A-Za-z0-9_])/y,
+    ],
+    ["number", /(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?/y],
+    ["ident", /[A-Za-z_:][A-Za-z0-9_:]*/y],
+    ["string", /"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'|`[^`]*`/y],
+    // Range / subquery brackets stay raw: their content (`5m`, `$__range`,
+    // `86400s`, `5m:1m`) never names a label.
+    ["range", /\[[^\]]*\]/y],
+    ["punct", /=~|!~|!=|==|>=|<=|[(){},=<>+\-*/%^@]/y],
+];
+const WHITESPACE = /\s+/y;
+function tokenize(src) {
+    const tokens = [];
+    let pos = 0;
+    while (pos < src.length) {
+        WHITESPACE.lastIndex = pos;
+        if (WHITESPACE.test(src)) {
+            pos = WHITESPACE.lastIndex;
+            continue;
+        }
+        const token = lexemeAt(src, pos);
+        tokens.push(token);
+        pos += token.text.length;
+    }
+    tokens.push({ kind: "eof", text: "", pos });
+    return tokens;
+}
+function lexemeAt(src, pos) {
+    for (const [kind, pattern] of LEXEMES) {
+        pattern.lastIndex = pos;
+        const match = pattern.exec(src);
+        if (match)
+            return { kind, text: match[0], pos };
+    }
+    throw new Error(`PromQL: unexpected "${src[pos]}" at ${pos} in: ${src}`);
+}
+/** String literal → value (Go-style escapes reduced to the escaped character). */
+function unquote(text) {
+    const body = text.slice(1, -1);
+    return text.startsWith("`") ? body : body.replace(/\\(.)/g, "$1");
+}
+// ── Parser ─────────────────────────────────────────────────────────────────
+const AGGREGATORS = new Set("sum min max avg group stddev stdvar count count_values bottomk topk quantile limitk limit_ratio".split(" "));
+const BINARY_PRECEDENCE = {
+    or: 1,
+    and: 2,
+    unless: 2,
+    "==": 3,
+    "!=": 3,
+    "<=": 3,
+    "<": 3,
+    ">=": 3,
+    ">": 3,
+    "+": 4,
+    "-": 4,
+    "*": 5,
+    "/": 5,
+    "%": 5,
+    atan2: 5,
+    "^": 6,
+};
+const MATCH_OPS = new Set(["=", "!=", "=~", "!~"]);
+class Parser {
+    tokens;
+    src;
+    i = 0;
+    constructor(tokens, src) {
+        this.tokens = tokens;
+        this.src = src;
+    }
+    parse() {
+        const node = this.parseExpr(1);
+        this.expectKind("eof");
+        return node;
+    }
+    peek() {
+        return this.tokens[this.i];
+    }
+    next() {
+        const token = this.tokens[this.i];
+        if (token.kind !== "eof")
+            this.i++;
+        return token;
+    }
+    peekIs(text) {
+        const t = this.peek();
+        return (t.kind === "ident" || t.kind === "punct") && t.text === text;
+    }
+    accept(text) {
+        if (!this.peekIs(text))
+            return false;
+        this.i++;
+        return true;
+    }
+    expect(text) {
+        if (!this.accept(text))
+            throw this.error(`"${text}"`);
+    }
+    expectKind(kind) {
+        if (this.peek().kind !== kind)
+            throw this.error(kind);
+        return this.next();
+    }
+    error(expected) {
+        const t = this.peek();
+        return new Error(`PromQL: expected ${expected} at ${t.pos}, got "${t.text || "<end>"}" in: ${this.src}`);
+    }
+    binaryPrecedence() {
+        const t = this.peek();
+        if (t.kind !== "punct" && t.kind !== "ident")
+            return undefined;
+        return Object.hasOwn(BINARY_PRECEDENCE, t.text) ? BINARY_PRECEDENCE[t.text] : undefined;
+    }
+    parseExpr(minPrec) {
+        let lhs = this.parseUnary();
+        for (;;) {
+            const prec = this.binaryPrecedence();
+            if (prec === undefined || prec < minPrec)
+                return lhs;
+            const op = this.next().text;
+            const matching = this.parseVectorMatching();
+            // `^` is right-associative; every other operator binds left.
+            const rhs = this.parseExpr(op === "^" ? prec : prec + 1);
+            lhs = { type: "binary", op, lhs, rhs, matching };
+        }
+    }
+    parseVectorMatching() {
+        this.accept("bool");
+        let mode;
+        let labels = [];
+        if (this.peekIs("on") || this.peekIs("ignoring")) {
+            mode = this.next().text;
+            labels = this.parseLabelList();
+        }
+        let group;
+        let include = [];
+        if (this.peekIs("group_left") || this.peekIs("group_right")) {
+            group = this.next().text;
+            if (this.peekIs("("))
+                include = this.parseLabelList();
+        }
+        return mode || group ? { mode, labels, group, include } : undefined;
+    }
+    parseUnary() {
+        if (this.accept("-") || this.accept("+"))
+            return this.parseUnary();
+        return this.parsePostfix(this.parsePrimary());
+    }
+    /** Range / subquery brackets, `offset <duration>`, `@ <time>` — label-neutral. */
+    parsePostfix(node) {
+        for (;;) {
+            if (this.peek().kind === "range") {
+                this.next();
+            }
+            else if (this.accept("offset")) {
+                this.accept("-");
+                this.expectKind("duration");
+            }
+            else if (this.accept("@")) {
+                this.parseAtModifier();
+            }
+            else {
+                return node;
+            }
+        }
+    }
+    parseAtModifier() {
+        if (this.peek().kind === "number") {
+            this.next();
+            return;
+        }
+        if (!this.accept("start") && !this.accept("end"))
+            throw this.error("@ timestamp");
+        this.expect("(");
+        this.expect(")");
+    }
+    parsePrimary() {
+        const t = this.peek();
+        if (t.kind === "number") {
+            this.next();
+            return { type: "number" };
+        }
+        if (t.kind === "string") {
+            this.next();
+            return { type: "string", value: unquote(t.text) };
+        }
+        if (t.kind === "ident")
+            return this.parseIdentExpr(this.next().text);
+        if (this.accept("{"))
+            return this.parseSelectorBody(undefined);
+        if (!this.accept("("))
+            throw this.error("expression");
+        const inner = this.parseExpr(1);
+        this.expect(")");
+        return inner;
+    }
+    parseIdentExpr(name) {
+        const isAggregation = AGGREGATORS.has(name) && (this.peekIs("(") || this.peekIs("by") || this.peekIs("without"));
+        if (isAggregation)
+            return this.parseAggregate(name);
+        if (this.peekIs("("))
+            return { type: "call", func: name, args: this.parseArgs() };
+        if (this.accept("{"))
+            return this.parseSelectorBody(name);
+        return { type: "selector", name, matchers: [] };
+    }
+    parseAggregate(op) {
+        const before = this.parseGrouping();
+        const args = this.parseArgs();
+        const grouping = before ?? this.parseGrouping();
+        if (args.length < 1 || args.length > 2)
+            throw this.error(`1-2 arguments to ${op}`);
+        const expr = args[args.length - 1];
+        const param = args.length === 2 ? args[0] : undefined;
+        return { type: "aggregate", op, grouping, param, expr };
+    }
+    parseGrouping() {
+        if (!this.peekIs("by") && !this.peekIs("without"))
+            return undefined;
+        const mode = this.next().text;
+        return { mode, labels: this.parseLabelList() };
+    }
+    parseLabelList() {
+        this.expect("(");
+        const labels = [];
+        while (!this.accept(")")) {
+            labels.push(this.expectKind("ident").text);
+            if (!this.accept(",")) {
+                this.expect(")");
+                break;
+            }
+        }
+        return labels;
+    }
+    parseArgs() {
+        this.expect("(");
+        const args = [];
+        if (this.accept(")"))
+            return args;
+        do {
+            args.push(this.parseExpr(1));
+        } while (this.accept(","));
+        this.expect(")");
+        return args;
+    }
+    /** After `{`: `label op "value"` pairs up to the closing `}`. */
+    parseSelectorBody(name) {
+        const matchers = [];
+        while (!this.accept("}")) {
+            const label = this.expectKind("ident").text;
+            const op = this.peek().text;
+            if (this.peek().kind !== "punct" || !MATCH_OPS.has(op)) {
+                throw this.error("label matcher operator");
+            }
+            this.next();
+            const value = unquote(this.expectKind("string").text);
+            matchers.push({ label, op: op, value });
+            if (!this.accept(",")) {
+                this.expect("}");
+                break;
+            }
+        }
+        const byName = matchers.find((m) => m.label === "__name__" && m.op === "=")?.value;
+        return { type: "selector", name: name ?? byName, matchers };
+    }
+}
+/** Parse one PromQL expression; throws on anything outside the supported subset. */
+export function parsePromql(src) {
+    return new Parser(tokenize(src), src).parse();
+}
+//# sourceMappingURL=promql-parse.test-support.js.map

package/dist/promql-parse.test-support.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"promql-parse.test-support.js","sourceRoot":"","sources":["../src/promql-parse.test-support.ts"],"names":[],"mappings":"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"}

package/dist/promql-reading-rules.test-support.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Test support for the metrics contract's reading rules — never imported by
+ * runtime code. The label checker (`promql-labels.test-support.ts`) asks which
+ * labels a query names; this asks HOW it reads a series:
+ *
+ * - A counter or histogram series is read only inside the born-series count
+ *   `increaseIn` builds (contract rule 2): `increase()` alone never counts a
+ *   series' first sample, `rate()` neither. The one exception is a plain
+ *   `increase()` over a window of an hour or less at the retention edge,
+ *   which the caller allows through `plainIncreaseAllowed`.
+ * - A gauge is read only node-folded (contract rule 3): directly inside
+ *   `max by (<exactly its contract labels>)(…)`.
+ *
+ * Text-level on purpose: the shapes are fixed strings the helpers emit and the
+ * alert rules and dashboards copy, so any other spelling is a violation.
+ */
+/** The subset of a `metrics-contract.json` entry the rules need. */
+export interface ReadingRuleMetric {
+    promName: string;
+    type: string;
+    labels: readonly string[];
+}
+export interface ReadingRuleOptions {
+    /** Whether a plain `increase(<range>[ @ <at>])` is allowed; never, when absent. */
+    plainIncreaseAllowed?: (range: string, at: number | undefined) => boolean;
+}
+/** Every violation of the reading rules in one PromQL string. */
+export declare function readingRuleViolations(promql: string, metrics: readonly ReadingRuleMetric[], options?: ReadingRuleOptions): string[];
+//# sourceMappingURL=promql-reading-rules.test-support.d.ts.map

package/dist/promql-reading-rules.test-support.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"promql-reading-rules.test-support.d.ts","sourceRoot":"","sources":["../src/promql-reading-rules.test-support.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,oEAAoE;AACpE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;CAC1B;AAED,MAAM,WAAW,kBAAkB;IACjC,mFAAmF;IACnF,oBAAoB,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,SAAS,KAAK,OAAO,CAAA;CAC1E;AAsBD,iEAAiE;AACjE,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,SAAS,iBAAiB,EAAE,EACrC,OAAO,GAAE,kBAAuB,GAC/B,MAAM,EAAE,CAmBV"}

package/dist/promql-reading-rules.test-support.js

@@ -0,0 +1,79 @@
+/**
+ * Test support for the metrics contract's reading rules — never imported by
+ * runtime code. The label checker (`promql-labels.test-support.ts`) asks which
+ * labels a query names; this asks HOW it reads a series:
+ *
+ * - A counter or histogram series is read only inside the born-series count
+ *   `increaseIn` builds (contract rule 2): `increase()` alone never counts a
+ *   series' first sample, `rate()` neither. The one exception is a plain
+ *   `increase()` over a window of an hour or less at the retention edge,
+ *   which the caller allows through `plainIncreaseAllowed`.
+ * - A gauge is read only node-folded (contract rule 3): directly inside
+ *   `max by (<exactly its contract labels>)(…)`.
+ *
+ * Text-level on purpose: the shapes are fixed strings the helpers emit and the
+ * alert rules and dashboards copy, so any other spelling is a violation.
+ */
+const SERIES = String.raw `camunda_[A-Za-z0-9_]+(?:\{[^}]*\})?`;
+const RANGE = String.raw `[^\]\s]+`;
+const OFFSET = String.raw `[^)\s]+`;
+/**
+ * `((increase(S[R]@) and present_over_time(S[1h]@ offset O)) or
+ * (max_over_time(S[R]@) unless present_over_time(S[1h]@ offset O)))` — O is
+ * the window's range, or the end of its first hour at the retention edge.
+ */
+const BORN_READ = new RegExp(String.raw `\(\(increase\((${SERIES})\[(${RANGE})\]((?: @ \d+)?)\) and present_over_time\(\1\[1h\]\3 offset (${OFFSET})\)\)` +
+    String.raw ` or \(max_over_time\(\1\[\2\]\3\) unless present_over_time\(\1\[1h\]\3 offset \4\)\)\)`, "g");
+const PLAIN_INCREASE = new RegExp(String.raw `increase\((${SERIES})\[(${RANGE})\](?: @ (\d+))?\)`, "g");
+/** Every violation of the reading rules in one PromQL string. */
+export function readingRuleViolations(promql, metrics, options = {}) {
+    const violations = [];
+    const covered = coveredSpans(promql, options);
+    for (const metric of metrics) {
+        for (const index of occurrences(promql, metric)) {
+            if (metric.type === "gauge") {
+                if (!nodeFolded(promql, index, metric.labels)) {
+                    violations.push(`${metric.promName} is not read as max by (${metric.labels.join(", ")})(…) — fold a clustered engine's nodes first`);
+                }
+            }
+            else if (!covered.some(([from, to]) => index >= from && index < to)) {
+                violations.push(`${metric.promName} is read outside the born-series count (increaseIn) — increase()/rate() miss a series' first sample`);
+            }
+        }
+    }
+    return violations;
+}
+/** The spans counters may appear in: born-series reads, plus the allowed plain increases. */
+function coveredSpans(promql, options) {
+    const spans = [];
+    for (const m of promql.matchAll(BORN_READ))
+        spans.push([m.index, m.index + m[0].length]);
+    for (const m of promql.matchAll(PLAIN_INCREASE)) {
+        const inBorn = spans.some(([from, to]) => m.index >= from && m.index < to);
+        const at = m[3] === undefined ? undefined : Number(m[3]);
+        if (!inBorn && options.plainIncreaseAllowed?.(m[2], at)) {
+            spans.push([m.index, m.index + m[0].length]);
+        }
+    }
+    return spans;
+}
+/** Start offsets of the metric's series names (histograms: `_sum`/`_count`/`_bucket`). */
+function occurrences(promql, metric) {
+    const names = metric.type === "histogram"
+        ? ["_sum", "_count", "_bucket"].map((suffix) => `${metric.promName}${suffix}`)
+        : [metric.promName];
+    const pattern = new RegExp(String.raw `\b(?:${names.join("|")})(?![A-Za-z0-9_])`, "g");
+    return [...promql.matchAll(pattern)].map((m) => m.index);
+}
+/** Whether the gauge at `index` sits directly inside `max by (<labels>)(`. */
+function nodeFolded(promql, index, labels) {
+    const before = /max\s+by\s*\(([^)]*)\)\s*\(\s*$/.exec(promql.slice(0, index));
+    if (!before)
+        return false;
+    const folded = before[1]
+        .split(",")
+        .map((label) => label.trim())
+        .filter((label) => label !== "");
+    return folded.length === labels.length && labels.every((label) => folded.includes(label));
+}
+//# sourceMappingURL=promql-reading-rules.test-support.js.map

package/dist/promql-reading-rules.test-support.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"promql-reading-rules.test-support.js","sourceRoot":"","sources":["../src/promql-reading-rules.test-support.ts"],"names":[],"mappings":"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"}

package/dist/promql-reading-rules.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=promql-reading-rules.test.d.ts.map

package/dist/promql-reading-rules.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"promql-reading-rules.test.d.ts","sourceRoot":"","sources":["../src/promql-reading-rules.test.ts"],"names":[],"mappings":""}

package/dist/promql-reading-rules.test.js

@@ -0,0 +1,61 @@
+import { describe, expect, it } from "vitest";
+import { readingRuleViolations, } from "./promql-reading-rules.test-support.js";
+import { engineState, increaseIn } from "./queries/helpers.js";
+const METRICS = [
+    { promName: "camunda_inc_total", type: "counter", labels: ["engine_id"] },
+    { promName: "camunda_dur_milliseconds", type: "histogram", labels: ["engine_id"] },
+    { promName: "camunda_open", type: "gauge", labels: ["process_definition_key", "engine_id"] },
+];
+const violations = (promql, plainIncreaseAllowed) => readingRuleViolations(promql, METRICS, { plainIncreaseAllowed });
+describe("readingRuleViolations — counters and histograms", () => {
+    it("accepts the born-series count, rolling and pinned, with a selector", () => {
+        const born = (series, range, at) => `((increase(${series}[${range}]${at === undefined ? "" : ` @ ${at}`}) and present_over_time(${series}[1h]${at === undefined ? "" : ` @ ${at}`} offset ${range})) or (max_over_time(${series}[${range}]${at === undefined ? "" : ` @ ${at}`}) unless present_over_time(${series}[1h]${at === undefined ? "" : ` @ ${at}`} offset ${range})))`;
+        expect(violations(`sum(${born('camunda_inc_total{engine_id="a"}', "7d")})`)).toEqual([]);
+        expect(violations(`histogram_quantile(0.95, sum by (le)(${born("camunda_dur_milliseconds_bucket", "86400s", 1700000000)}))`)).toEqual([]);
+        expect(violations(`sum(${born("camunda_inc_total", "$__range")})`)).toEqual([]);
+    });
+    it("rejects a plain increase(), rate() or a raw counter", () => {
+        expect(violations("sum(increase(camunda_inc_total[7d]))")).toHaveLength(1);
+        expect(violations("sum(rate(camunda_inc_total[5m])) * 60")).toHaveLength(1);
+        expect(violations("sum(camunda_dur_milliseconds_sum)")).toHaveLength(1);
+    });
+    it("rejects a born-series count whose parts disagree", () => {
+        // The two silence checks must look at the same hour …
+        const offsets = "((increase(camunda_inc_total[7d]) and present_over_time(camunda_inc_total[1h] offset 7d)) or (max_over_time(camunda_inc_total[7d]) unless present_over_time(camunda_inc_total[1h] offset 1d)))";
+        expect(violations(offsets).length).toBeGreaterThan(0);
+        // … and both reads span the same window.
+        const ranges = "((increase(camunda_inc_total[7d]) and present_over_time(camunda_inc_total[1h] offset 7d)) or (max_over_time(camunda_inc_total[1d]) unless present_over_time(camunda_inc_total[1h] offset 7d)))";
+        expect(violations(ranges).length).toBeGreaterThan(0);
+    });
+    it("accepts the window's own first hour as the silence check at the retention edge", () => {
+        const edge = "((increase(camunda_inc_total[30d]) and present_over_time(camunda_inc_total[1h] offset 2588400s)) or (max_over_time(camunda_inc_total[30d]) unless present_over_time(camunda_inc_total[1h] offset 2588400s)))";
+        expect(violations(`sum(${edge})`)).toEqual([]);
+    });
+    it("lets a plain increase() through only where the caller allows its window", () => {
+        const allowed = (range) => range === "30d";
+        expect(violations("sum(increase(camunda_inc_total[30d]))", allowed)).toEqual([]);
+        expect(violations("sum(increase(camunda_inc_total[7d]))", allowed)).toHaveLength(1);
+    });
+    it("accepts exactly what increaseIn emits", () => {
+        expect(violations(`sum(${increaseIn('camunda_inc_total{engine_id="a"}', { range: "7d" })})`)).toEqual([]);
+        expect(violations(`sum(${increaseIn("camunda_dur_milliseconds_sum", { range: "3600s", at: Math.floor(Date.now() / 1000) })})`)).toEqual([]);
+    });
+});
+describe("readingRuleViolations — gauges", () => {
+    it("accepts a gauge folded over exactly its contract labels, in any order", () => {
+        expect(violations('sum(max by (engine_id, process_definition_key)(camunda_open{engine_id="a"}))')).toEqual([]);
+        expect(violations("max by (process_definition_key, engine_id) (camunda_open)")).toEqual([]);
+    });
+    it("rejects a summed, partly folded or over-folded gauge", () => {
+        expect(violations("sum(camunda_open)")).toHaveLength(1);
+        expect(violations("sum by (engine_id)(max by (engine_id)(camunda_open))")).toHaveLength(1);
+        expect(violations("max by (engine_id, process_definition_key, instance)(camunda_open)")).toHaveLength(1);
+        expect(violations("max(camunda_open)")).toHaveLength(1);
+    });
+});
+describe("engineState", () => {
+    it("folds a gauge over its contract labels", () => {
+        expect(engineState("camunda_incidents_open", '{engine_id="a"}')).toBe('max by (process_definition_key, incident_type, engine_id)(camunda_incidents_open{engine_id="a"})');
+    });
+});
+//# sourceMappingURL=promql-reading-rules.test.js.map

package/dist/promql-reading-rules.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"promql-reading-rules.test.js","sourceRoot":"","sources":["../src/promql-reading-rules.test.ts"],"names":[],"mappings":"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"}

package/dist/promql-sources.test-support.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Test support for the metrics-contract guards — never imported by runtime
+ * code. Extracts the PromQL the non-TypeScript consumers send: the alert
+ * rules' `expr:` values (alerts.yml) and the Grafana dashboards' panel `expr`s
+ * and templating queries, for the label checker
+ * (`promql-labels.test-support.ts`).
+ *
+ * Both extractors fail closed. A source shape they do not understand throws
+ * instead of being skipped or passed through raw: a skipped expression is one
+ * the label guard never checks, and a still-quoted one parses as a single
+ * PromQL string literal that checks zero labels — either way the guard would
+ * pass vacuously.
+ */
+/**
+ * The `expr:` values of the alert rules, as the YAML scalars they denote:
+ * plain, single- or double-quoted, or a `|`/`>` block scalar, each possibly
+ * running over continuation lines (joined with a space — PromQL does not care
+ * about line breaks).
+ */
+export declare function alertExpressions(yaml: string): string[];
+/**
+ * Every panel `expr` of a Grafana dashboard, plus its templating variable
+ * queries: `label_values(series, label)` becomes the equivalent
+ * `count by (label)(series)`, so the label is checked like any grouping, and
+ * `query_result(expr)` contributes its expression. Other `query` strings
+ * (custom variable lists, `label_names()`, `metrics()`) name no label.
+ */
+export declare function dashboardQueries(node: unknown): string[];
+//# sourceMappingURL=promql-sources.test-support.d.ts.map

package/dist/promql-sources.test-support.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"promql-sources.test-support.d.ts","sourceRoot":"","sources":["../src/promql-sources.test-support.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAyBvD;AAwBD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,EAAE,CAUxD"}

package/dist/promql-sources.test-support.js

@@ -0,0 +1,112 @@
+/**
+ * Test support for the metrics-contract guards — never imported by runtime
+ * code. Extracts the PromQL the non-TypeScript consumers send: the alert
+ * rules' `expr:` values (alerts.yml) and the Grafana dashboards' panel `expr`s
+ * and templating queries, for the label checker
+ * (`promql-labels.test-support.ts`).
+ *
+ * Both extractors fail closed. A source shape they do not understand throws
+ * instead of being skipped or passed through raw: a skipped expression is one
+ * the label guard never checks, and a still-quoted one parses as a single
+ * PromQL string literal that checks zero labels — either way the guard would
+ * pass vacuously.
+ */
+/** `|`/`>` block-scalar headers, with optional chomping and indentation indicators. */
+const BLOCK_SCALAR = /^[|>](?:[1-9]?[-+]?|[-+][1-9])$/;
+/**
+ * The `expr:` values of the alert rules, as the YAML scalars they denote:
+ * plain, single- or double-quoted, or a `|`/`>` block scalar, each possibly
+ * running over continuation lines (joined with a space — PromQL does not care
+ * about line breaks).
+ */
+export function alertExpressions(yaml) {
+    const lines = yaml.split("\n");
+    const out = [];
+    for (let i = 0; i < lines.length; i++) {
+        // The key may open a list item (`- expr: …`); the dash counts as indentation.
+        const match = /^(\s*(?:-\s+)?)expr:(.*)$/.exec(lines[i]);
+        if (!match)
+            continue;
+        const [, keyIndent, rest] = match;
+        const line = i + 1;
+        // The value runs until the first non-blank line indented no deeper than the key.
+        const continuation = [];
+        for (; i + 1 < lines.length; i++) {
+            const next = lines[i + 1];
+            if (next.trim() === "")
+                continue;
+            if (next.length - next.trimStart().length <= keyIndent.length)
+                break;
+            continuation.push(next.trim());
+        }
+        const inline = rest.trim();
+        const value = BLOCK_SCALAR.test(inline)
+            ? continuation.join(" ")
+            : yamlFlowScalar([inline, ...continuation].join(" ").trim());
+        if (value === "")
+            throw new Error(`alerts.yml: empty expr at line ${line}`);
+        out.push(value);
+    }
+    return out;
+}
+/**
+ * The string a plain or quoted YAML flow scalar denotes. Single quotes escape
+ * only `''`; double quotes use backslash escapes, parsed as their JSON subset —
+ * anything beyond it (or a trailing comment after the closing quote) throws.
+ */
+function yamlFlowScalar(text) {
+    if (text.startsWith("'")) {
+        if (!/^'(?:[^']|'')*'$/.test(text)) {
+            throw new Error(`alerts.yml: unsupported single-quoted expr: ${text}`);
+        }
+        return text.slice(1, -1).replaceAll("''", "'");
+    }
+    if (text.startsWith('"')) {
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            throw new Error(`alerts.yml: unsupported double-quoted expr: ${text}`);
+        }
+    }
+    return text;
+}
+/**
+ * Every panel `expr` of a Grafana dashboard, plus its templating variable
+ * queries: `label_values(series, label)` becomes the equivalent
+ * `count by (label)(series)`, so the label is checked like any grouping, and
+ * `query_result(expr)` contributes its expression. Other `query` strings
+ * (custom variable lists, `label_names()`, `metrics()`) name no label.
+ */
+export function dashboardQueries(node) {
+    if (Array.isArray(node))
+        return node.flatMap(dashboardQueries);
+    if (node === null || typeof node !== "object")
+        return [];
+    const out = [];
+    for (const [key, value] of Object.entries(node)) {
+        if (typeof value !== "string")
+            out.push(...dashboardQueries(value));
+        else if (key === "expr")
+            out.push(value);
+        else if (key === "query")
+            out.push(...templatingQuery(value));
+    }
+    return out;
+}
+/** The PromQL behind one templating `query`; throws on a label-naming call it cannot read. */
+function templatingQuery(query) {
+    const fn = /^\s*(label_values|query_result)\s*\(/.exec(query)?.[1];
+    if (!fn)
+        return [];
+    const args = new RegExp(`^\\s*${fn}\\s*\\(([\\s\\S]*)\\)\\s*$`).exec(query)?.[1].trim();
+    if (fn === "query_result" && args)
+        return [args];
+    // label_values(<series selector>, <label>): the label is the LAST argument —
+    // the selector itself may contain commas between its matchers.
+    const labelValues = args && /^([\s\S]+),\s*([A-Za-z_][A-Za-z0-9_]*)$/.exec(args);
+    if (labelValues)
+        return [`count by (${labelValues[2]})(${labelValues[1].trim()})`];
+    throw new Error(`unsupported Grafana templating query (extend dashboardQueries for it): ${query}`);
+}
+//# sourceMappingURL=promql-sources.test-support.js.map