metergraph-cli 0.2.0 → 0.2.2

package/src/style.js

@@ -0,0 +1,101 @@
+import { EXIT_CODES } from "./constants.js";
+
+// Presentation for human (non --json) output: a status headline, aligned
+// fields and next steps. Color is used only when the stream is a terminal
+// and NO_COLOR is unset (https://no-color.org); FORCE_COLOR turns it on.
+// Symbols are plain Unicode and are printed with or without color.
+
+const CODES = { bold: [1, 22], dim: [2, 22], red: [31, 39], green: [32, 39], yellow: [33, 39], cyan: [36, 39] };
+
+function makeStyle(color, width = Infinity) {
+  const style = { color, width };
+  for (const [name, [open, close]] of Object.entries(CODES)) {
+    style[name] = color ? (text) => `\u001b[${open}m${text}\u001b[${close}m` : (text) => String(text);
+  }
+  return style;
+}
+
+export const PLAIN = makeStyle(false);
+
+// Prose wraps to the terminal width only on a terminal, so piped output keeps
+// one line per message.
+export function createStyle(stream, env = process.env) {
+  const tty = Boolean(stream?.isTTY);
+  const width = tty ? Math.min(Math.max(stream.columns || 80, 40), 100) - 2 : Infinity;
+  if (env.NO_COLOR) return makeStyle(false, width);
+  if (env.FORCE_COLOR && env.FORCE_COLOR !== "0") return makeStyle(true, width);
+  return makeStyle(tty && env.TERM !== "dumb", width);
+}
+
+const TONES = {
+  ok: ["✓", "green"],
+  warn: ["!", "yellow"],
+  fail: ["✗", "red"],
+  info: ["•", "cyan"],
+};
+
+// ok for success; warn when the command stopped for a person to act;
+// fail for everything else.
+export function toneFor(outcome) {
+  if (outcome === "ok") return "ok";
+  if (outcome === "action_required" || outcome === "authentication_required") return "warn";
+  return "fail";
+}
+
+export function headline(style, tone, title, outcome = null) {
+  const [icon, color] = TONES[tone];
+  let line = `${style[color](icon)} ${style.bold(title)}`;
+  if (outcome !== null && outcome !== "ok") line += `  ${style.dim(`(${outcome}, exit ${EXIT_CODES[outcome]})`)}`;
+  return line;
+}
+
+// Aligned "label  value" rows. Rows whose value is null or undefined are left out.
+export function fields(style, rows, indent = "  ") {
+  const shown = rows.filter(([, value]) => value !== null && value !== undefined);
+  const width = Math.max(0, ...shown.map(([label]) => label.length));
+  return shown.map(([label, value]) => `${indent}${style.dim(label.padEnd(width))}  ${value}`);
+}
+
+// Indents prose and wraps it to style.width.
+export function paragraph(style, text, indent = "  ") {
+  const width = style.width;
+  const lines = [];
+  let line = "";
+  for (const word of String(text).split(/\s+/).filter(Boolean)) {
+    if (line && indent.length + line.length + 1 + word.length > width) {
+      lines.push(indent + line);
+      line = word;
+    } else {
+      line = line ? `${line} ${word}` : word;
+    }
+  }
+  if (line) lines.push(indent + line);
+  return lines;
+}
+
+// "→ label  value" rows for what to do next, aligned like fields.
+export function steps(style, rows) {
+  const shown = rows.filter(([, value]) => value !== null && value !== undefined);
+  const width = Math.max(0, ...shown.map(([label]) => label.length));
+  return shown.flatMap(([label, value]) => {
+    if (label) return [`${style.cyan("→")} ${label.padEnd(width)}  ${value}`];
+    // Unlabeled steps are prose: wrap them with a hanging indent.
+    const [first, ...rest] = paragraph(style, value, "  ");
+    return [`${style.cyan("→")} ${first.trimStart()}`, ...rest];
+  });
+}
+
+export function section(style, title) {
+  return style.bold(title);
+}
+
+export function render(lines) {
+  // Collapse runs of blank lines and trim blank edges.
+  const out = [];
+  for (const line of lines) {
+    if (line === "" && (out.length === 0 || out[out.length - 1] === "")) continue;
+    out.push(line);
+  }
+  while (out.length > 0 && out[out.length - 1] === "") out.pop();
+  return `${out.join("\n")}\n`;
+}

package/src/transport.js

@@ -1,16 +1,17 @@
 import http from "node:http";
 import https from "node:https";
 
-import { PACKAGE_NAME, READ_QUERY_KEYS, VERSION } from "./constants.js";
+import { MAX_QUERY_LENGTH, PACKAGE_NAME, READ_QUERY_KEYS, READ_QUERY_REPEATABLE, VERSION } from "./constants.js";
 import { classifyError } from "./http.js";
 
 const USER_AGENT = `${PACKAGE_NAME}/${VERSION}`;
-const MAX_QUERY_LENGTH = 2048;
+// MAX_QUERY_LENGTH is shared with argument validation (constants.js).
 
 // Builds the request URL. Without a query the path must be a fixed path on
 // the origin with no search part. A query is accepted only as a
 // URLSearchParams the caller built, only on a path in READ_QUERY_KEYS, only
-// with that path's keys, each at most once. Anything else is a programming
+// with that path's keys, each at most once unless READ_QUERY_REPEATABLE lists
+// it for that path. Anything else is a programming
 // error, so no input can choose another path, origin or header.
 function requestUrl(origin, pathname, query) {
   const url = new URL(pathname, origin);
@@ -23,9 +24,12 @@ function requestUrl(origin, pathname, query) {
   if (!(query instanceof URLSearchParams) || allowed === null) {
     throw new Error("a query is not allowed on this path");
   }
+  const repeatable = READ_QUERY_REPEATABLE[pathname] ?? [];
   const seen = new Set();
   for (const key of query.keys()) {
-    if (!allowed.includes(key) || seen.has(key)) throw new Error("query key is not allowed");
+    if (!allowed.includes(key) || (seen.has(key) && !repeatable.includes(key))) {
+      throw new Error("query key is not allowed");
+    }
     seen.add(key);
   }
   const search = query.toString();

package/src/usage-aggregates.js

@@ -0,0 +1,197 @@
+import { GROUP_KEY } from "./read-contract.js";
+
+// Ranking and prior-period comparison for grouped usage. Both work on reports
+// already validated by usageAggregatesReport and say when the returned groups
+// are not every group, so a ranking or a change is never presented as
+// complete when it is not.
+
+const HOUR_MS = 60 * 60 * 1000;
+const DAY_MS = 24 * HOUR_MS;
+
+// A group's value for one dimension. A metadata dimension's value is
+// metadata_value, and the group of calls without one is told apart from an
+// empty string.
+const valueOf = (item, dimension) =>
+  dimension.startsWith("metadata.") ? (item.has_value ? item.metadata_value ?? "" : null) : item[dimension];
+// Groups are joined by the raw group values the validator kept (GROUP_KEY),
+// never by display values, which can be null for text that is unsafe to show.
+const byKey = (groupBy) => (item) =>
+  item[GROUP_KEY] ?? JSON.stringify(groupBy.map((dimension) => valueOf(item, dimension) ?? null));
+const desc = (pick) => (a, b) => {
+  const left = pick(a);
+  const right = pick(b);
+  // Unknown values (null) rank last, whichever direction.
+  if (left === null && right === null) return 0;
+  if (left === null) return 1;
+  if (right === null) return -1;
+  return right - left;
+};
+const then = (...orders) => (a, b) => {
+  for (const order of orders) {
+    const result = order(a, b);
+    if (result !== 0) return result;
+  }
+  return 0;
+};
+
+// The service orders groups by cost, then calls, then group key. Every other
+// order is applied here over the returned groups.
+const ORDERS = {
+  cost: [desc((item) => item.cost_usd), desc((item) => item.calls)],
+  "cost-per-call": [desc((item) => item.cost_per_call_usd), desc((item) => item.cost_usd)],
+  calls: [desc((item) => item.calls), desc((item) => item.cost_usd)],
+  errors: [desc((item) => item.error_calls), desc((item) => item.error_rate), desc((item) => item.calls)],
+  "avg-latency": [desc((item) => item.latency.avg_ms), desc((item) => item.calls)],
+  "p95-latency": [desc((item) => item.latency.p95_ms), desc((item) => item.calls)],
+  day: [(a, b) => (a.day < b.day ? -1 : a.day > b.day ? 1 : 0), desc((item) => item.cost_usd)],
+};
+
+// What each order means, for JSON and text output.
+export const SORT_LABELS = Object.freeze({
+  cost: "cost, highest first",
+  "cost-per-call": "cost per call (cost_usd / calls), highest first",
+  calls: "calls, most first",
+  errors: "error calls, most first",
+  "avg-latency": "mean latency over calls that reported one, highest first",
+  "p95-latency": "estimated p95 latency (fixed histogram), highest first",
+  day: "UTC day, oldest first",
+});
+
+// Orders the report's items and numbers them. A ranking other than by cost
+// over a cut list (the service returns the top groups by cost) is not a
+// ranking of every group, and says so.
+export function rankReport(report, sort, notices) {
+  const key = byKey(report.group_by);
+  const order = then(...ORDERS[sort], (a, b) => (key(a) < key(b) ? -1 : key(a) > key(b) ? 1 : 0));
+  const items = [...report.items].sort(order).map((item, index) => ({ rank: index + 1, ...item }));
+  const rankingComplete = sort === "cost" || !report.truncated;
+  if (!rankingComplete) notices.add("ranking_partial");
+  return {
+    ...report,
+    items,
+    sort: { by: sort, meaning: SORT_LABELS[sort], complete: rankingComplete },
+  };
+}
+
+// The window to compare with, from the current window the service read.
+// "previous" is the whole period before: for a preset of N UTC days, the N
+// whole UTC days before the current UTC day's start, even though the current
+// window ends part way through today. "previous-same-time" ends the prior
+// window at the same elapsed time, so both windows are the same length.
+export function priorWindow(window, mode) {
+  const since = Date.parse(window.since);
+  const until = Date.parse(window.until);
+  const length = window.preset === "utc_days" ? window.days * DAY_MS : until - since;
+  const priorSince = since - length;
+  const priorUntil = mode === "previous" ? since : priorSince + (until - since);
+  return { since: new Date(priorSince).toISOString(), until: new Date(priorUntil).toISOString() };
+}
+
+// The service reports amounts to 8 decimals; keep that precision and take the
+// percentage from the unrounded difference.
+const change = (now, before) => {
+  if (now === null || before === null) return { delta: null, percent: null };
+  const raw = now - before;
+  return {
+    delta: Math.round(raw * 1e8) / 1e8,
+    percent: before === 0 ? null : Math.round((raw / before) * 1000) / 10,
+  };
+};
+// A cost change is known only when both sides' cost is exact: a lower bound
+// can hide a larger true cost and reverse the direction.
+const exact = (pricing) => pricing?.cost === "exact";
+const costChange = (now, before, nowPricing, beforePricing) =>
+  exact(nowPricing) && exact(beforePricing) ? change(now, before) : { delta: null, percent: null };
+// A window's totals are the whole question only when its evidence and
+// coverage are complete (rows cut at --limit do not matter for totals);
+// otherwise unseen calls could reverse a change, so none is reported.
+const covered = (report) =>
+  report.evidence?.complete !== false &&
+  (report.coverage === null || report.coverage === undefined || report.coverage.completeness === "complete");
+
+const sideOf = (item) => ({ calls: item.calls, error_calls: item.error_calls, cost_usd: item.cost_usd, pricing: item.pricing });
+
+// Joins the current and prior reports group by group. A group missing from a
+// window whose groups are all listed had no calls there (zero); missing from
+// a cut window it is unknown (null), never zero.
+export function compareReports(current, prior, mode, notices) {
+  const key = byKey(current.group_by);
+  const priorByKey = new Map(prior.items.map((item) => [key(item), item]));
+  const currentKeys = new Set(current.items.map(key));
+  // No calls in a fully listed window: zero, and exactly so.
+  const zero = {
+    calls: 0, error_calls: 0, cost_usd: 0,
+    pricing: { priced_calls: 0, zero_cost_calls: 0, partial_calls: 0, unpriced_calls: 0, unknown_calls: 0, cost: "exact" },
+  };
+  // Absence proves zero only in a window whose evidence is complete (not cut,
+  // and nothing pending, clipped or unknown); otherwise it is unknown.
+  const absent = (report) => (report.complete ? zero : null);
+  const group = (item) => Object.fromEntries(current.group_by.flatMap((dimension) =>
+    dimension.startsWith("metadata.")
+      ? [["metadata_key", item.metadata_key], ["metadata_value", item.metadata_value], ["has_value", item.has_value]]
+      : [[dimension, item[dimension]]]));
+  const bothCovered = covered(current) && covered(prior);
+  const unknownChange = { delta: null, percent: null };
+  const row = (item, now, before) => ({
+    ...group(item),
+    current: now,
+    prior: before,
+    cost_change: bothCovered
+      ? costChange(now?.cost_usd ?? null, before?.cost_usd ?? null, now?.pricing, before?.pricing)
+      : unknownChange,
+    calls_change: bothCovered ? change(now?.calls ?? null, before?.calls ?? null) : unknownChange,
+  });
+  const items = current.items.map((item) => {
+    const match = priorByKey.get(key(item));
+    return row(item, sideOf(item), match === undefined ? absent(prior) : sideOf(match));
+  });
+  const onlyPrior = prior.items
+    .filter((item) => !currentKeys.has(key(item)))
+    .map((item) => row(item, absent(current), sideOf(item)));
+  const currentHours = current.window.hours;
+  const priorHours = prior.window.hours;
+  // A window that ends part way through the current UTC day compared with a
+  // longer prior period: totals are not like for like.
+  const unequal = Math.abs(currentHours - priorHours) > 0.01;
+  const partialAgainstFull = unequal && current.window.partial_days.length > 0;
+  if (partialAgainstFull) notices.add("partial_day_comparison");
+  const complete = current.complete && prior.complete;
+  if (!complete) notices.add("comparison_incomplete");
+  const totals = (report) => ({
+    calls: report.totals.calls,
+    error_calls: report.totals.error_calls,
+    cost_usd: report.totals.cost_usd,
+  });
+  const likeForLike = partialAgainstFull ? priorWindow(current.window, "previous-same-time") : null;
+  return {
+    mode,
+    prior: {
+      window: prior.window,
+      totals: prior.totals,
+      coverage: prior.coverage,
+      pricing: prior.pricing,
+      attribution: prior.attribution,
+      evidence: prior.evidence,
+      warnings: prior.warnings,
+      truncated: prior.truncated,
+      complete: prior.complete,
+      rows: prior.rows,
+      matched_groups: prior.matched_groups,
+    },
+    hours: { current: currentHours, prior: priorHours },
+    partial_day_compared_with_full: partialAgainstFull,
+    like_for_like_window: likeForLike,
+    complete,
+    totals: {
+      current: totals(current),
+      prior: totals(prior),
+      cost_change: bothCovered
+        ? costChange(current.totals.cost_usd, prior.totals.cost_usd, current.pricing, prior.pricing)
+        : unknownChange,
+      cost_change_known: bothCovered && exact(current.pricing) && exact(prior.pricing),
+      calls_change: bothCovered ? change(current.totals.calls, prior.totals.calls) : unknownChange,
+      calls_change_known: bothCovered,
+    },
+    items: [...items, ...onlyPrior],
+  };
+}

package/src/verify-output.js

@@ -1,3 +1,5 @@
+import { PLAIN, fields, headline, paragraph, render, steps, toneFor } from "./style.js";
+
 const MESSAGES = Object.freeze({
   invalid_trace_identity: "Provide exactly one exact trace or request ID from your application run.",
   invalid_invocation_window: "Provide the start and end timestamps of that application invocation.",
@@ -19,18 +21,26 @@ export function verifyMessage(outcome, reason) {
   return MESSAGES[reason] ?? `Trace verification stopped (${outcome}). No application traffic claim was made.`;
 }
 
-export function verifyText(result) {
+export function verifyText(result, style = PLAIN) {
   const data = result.data;
-  const lines = ["Metergraph exact trace verification", `Outcome: ${result.outcome} (exit ${result.exit_code})`];
+  const title = result.ok ? "Trace verified" : "Trace not verified";
+  const lines = [headline(style, toneFor(result.outcome), title, result.outcome), ""];
   if (data) {
-    lines.push(`Workspace: ${data.workspace.id}`, `Deployment: ${data.deployment_profile}`,
-      `Invocation source: ${data.invocation.source}`, `Attempts: ${data.attempts}`,
-      `Processed: ${data.readiness.processed}`, `Metadata available: ${data.readiness.metadata_available}`,
-      `Application traffic verified: ${data.application_traffic_verified}`);
-    if (data.trace) lines.push(`Trace ID: ${data.trace.trace_id}`);
-    if (data.app_url) lines.push(`Dashboard link${data.link_workspace_bound ? " (workspace bound)" : " (select the correct workspace)"}: ${data.app_url}`);
-    if (data.browser) lines.push(`Browser: ${data.browser}`);
+    lines.push(...fields(style, [
+      ["Workspace", data.workspace.id],
+      ["Deployment", data.deployment_profile],
+      ["Trace ID", data.trace?.trace_id ?? null],
+      ["Invocation source", data.invocation.source],
+      ["Attempts", data.attempts],
+      ["Processed", data.readiness.processed],
+      ["Metadata available", data.readiness.metadata_available],
+      ["Application traffic verified", data.application_traffic_verified],
+      ["Browser", data.browser ?? null],
+    ]), "");
+  }
+  if (result.error) lines.push(...paragraph(style, result.error.message), "");
+  if (data?.app_url) {
+    lines.push(...steps(style, [[data.link_workspace_bound ? "Dashboard" : "Dashboard (select the correct workspace)", data.app_url]]));
   }
-  if (result.error) lines.push(result.error.message);
-  return `${lines.join("\n")}\n`;
+  return render(lines);
 }