/** * Judging a value in an answer: "the power is under 5 000 W", "the status is playing", "the Prometheus query returned something". The answer is JSON; a path says * where the value is in it, and one comparison says whether it is fine. Everything here is pure — the asking is in endpointChecks.ts. * * A path is the dots and brackets people already write: `power.now`, `data.result[0].value[1]`, `items[2].name`, and `["a.b"]` for a name with a dot in it. * A leading `$.` is allowed and means nothing. */ export const VALUE_OPS = ["<", "<=", ">", ">=", "=", "!=", "contains", "exists"] as const; export type ValueOp = (typeof VALUE_OPS)[number]; const NUMERIC_OPS: readonly ValueOp[] = ["<", "<=", ">", ">="]; export const isValueOp = (op: string): op is ValueOp => (VALUE_OPS as readonly string[]).includes(op); type Step = string | number; /** A path into its steps, or null when it can't be read. */ export function parsePath(path: string): Step[] | null { let p = path.trim(); if (p.startsWith("$")) p = p.slice(1); if (p.startsWith(".")) p = p.slice(1); const steps: Step[] = []; let i = 0; while (i < p.length) { const c = p[i]; if (c === ".") { i++; if (i >= p.length || p[i] === "." || p[i] === "[") return null; } else if (c === "[") { const close = p.indexOf("]", i); if (close < 0) return null; const inner = p.slice(i + 1, close).trim(); i = close + 1; if (/^\d+$/.test(inner)) steps.push(Number(inner)); else if (/^(".*"|'.*')$/.test(inner) && inner.length >= 2) steps.push(inner.slice(1, -1)); else return null; } else { const m = /^[^.[\]]+/.exec(p.slice(i)); if (!m) return null; steps.push(m[0]); i += m[0].length; } } return steps.length > 0 ? steps : null; } export const isValuePath = (path: string) => parsePath(path) !== null; export type Read = { found: true; value: unknown } | { found: false; at: string }; /** What is at a path in a parsed answer. `at` says how far it got when it isn't there. */ export function readPath(json: unknown, path: string): Read { const steps = parsePath(path); if (!steps) return { found: false, at: path }; let here: unknown = json; const walked: string[] = []; for (const step of steps) { walked.push(typeof step === "number" ? `[${step}]` : walked.length === 0 ? step : `.${step}`); if (typeof step === "number") { if (!Array.isArray(here) || step >= here.length) return { found: false, at: walked.join("") }; here = here[step]; } else { if (here === null || typeof here !== "object" || Array.isArray(here) || !Object.prototype.hasOwnProperty.call(here, step)) return { found: false, at: walked.join("") }; here = (here as Record)[step]; } } return { found: true, value: here }; } /** A value as a number when it is one, or text that is one ("12.5": Prometheus gives its numbers as text); otherwise null. */ export function asNumber(value: unknown): number | null { if (typeof value === "number") return Number.isFinite(value) ? value : null; if (typeof value === "string" && value.trim() !== "" && Number.isFinite(Number(value))) return Number(value); return null; } /** A value as text, short enough to keep and show. */ export function showValue(value: unknown): string { const text = typeof value === "string" ? value : typeof value === "number" || typeof value === "boolean" || value === null ? String(value) : JSON.stringify(value); return text.length > 120 ? `${text.slice(0, 117)}…` : text; } export interface Verdict { ok: boolean; /** What was read, as text, to show and to remember. */ shown: string; /** The number, when it is one. */ number: number | null; message: string; } const WORDS: Record = { "<": "below", "<=": "at most", ">": "above", ">=": "at least", "=": "equal to", "!=": "anything but", contains: "containing", exists: "there" }; /** How a limit reads: "below 5000 W". */ export function describeLimit(op: ValueOp, expected: string | null, unit: string | null): string { if (op === "exists") return "there"; const n = asNumber(expected); const quoted = NUMERIC_OPS.includes(op) || n !== null ? String(expected) : `“${expected}”`; return `${WORDS[op]} ${quoted}${unit && (NUMERIC_OPS.includes(op) || n !== null) ? ` ${unit}` : ""}`; } /** Whether what was read meets the limit, and what to say about it. `read` is what readPath found. */ export function judgeValue(read: Read, path: string, op: ValueOp, expected: string | null, unit: string | null): Verdict { if (!read.found) { // "exists" is satisfied by the value being there, so its absence is the thing to say; the others cannot be judged without it. return { ok: false, shown: "", number: null, message: `there is no “${path}” in the answer (it stops at ${read.at})` }; } const number = asNumber(read.value); const shown = showValue(read.value); const withUnit = number !== null && unit ? `${shown} ${unit}` : shown; const limit = describeLimit(op, expected, unit); if (op === "exists") return { ok: true, shown, number, message: `${path} is ${withUnit}` }; let ok: boolean; if (NUMERIC_OPS.includes(op)) { const want = asNumber(expected); if (number === null) return { ok: false, shown, number, message: `${path} is “${shown}”, which isn't a number, so it can't be compared with ${expected}` }; if (want === null) return { ok: false, shown, number, message: `the limit “${expected}” isn't a number` }; ok = op === "<" ? number < want : op === "<=" ? number <= want : op === ">" ? number > want : number >= want; } else if (op === "contains") { ok = shown.includes(expected ?? ""); } else { // Numbers are equal as numbers ("5" and 5.0), anything else as the same text. const want = asNumber(expected); const same = number !== null && want !== null ? number === want : shown === (expected ?? ""); ok = op === "=" ? same : !same; } return { ok, shown, number, message: ok ? `${path} is ${withUnit} (should be ${limit})` : `${path} is ${withUnit}, but should be ${limit}` }; } /** Whether a saved check's value settings make sense together: the reason why not, or null. */ export function valueProblem(path: string | null, op: string | null, expected: string | null): string | null { if (!path && !op && !expected) return null; if (!path) return "Say where in the answer the value is, e.g. data.result[0].value[1]."; if (!isValuePath(path)) return "That isn't a path I can read. Use names separated by dots, and [0] for a place in a list, like data.result[0].value[1]."; if (!op || !isValueOp(op)) return "Say how the value should compare."; if (op !== "exists" && (expected === null || expected.trim() === "")) return "Say what to compare it with."; if (NUMERIC_OPS.includes(op) && asNumber(expected) === null) return "A limit to be above or below has to be a number."; return null; }