Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

15.7 KB
Raw Blame
/**
 * The cost center's controls and series shaping (features/usage/usage-controls.ts).
 *
 * - A calendar preset ends today and spans its day count inclusively; a trailing preset yields
 *   instant bounds plus the local dates they span; a range counts both ends.
 * - The range picks the precision: one per preset, a custom range scaling day → week → month,
 *   never more buckets than the server returns, timestamp precisions only for trailing presets.
 * - A bucket key reads short on the axis and in full in the bubble.
 * - The requests chart keeps its top entities and folds a tail of two or more into one summed,
 *   counted tail (success counts included); a tail of one keeps its name; by default every named
 *   series fits the palette.
 * - Series sum column by column; a bucket with nothing to rate has no rate (neither 0 nor a
 *   number), and is drawn at the top of the percent axis only so a line can cross it.
 * - Empty buckets are dropped (a request with no tokens still counts), shortening the axis and
 *   marking breaks where buckets were skipped; per-entity counts stay with their buckets.
 */
import { describe, expect, it } from "vitest";
import type { UsageSeriesPoint } from "@adelie/server/api";
import {
  bucketAxisLabel,
  bucketFullLabel,
  compactCounts,
  compactSeries,
  defaultGranularity,
  foldEntitySeries,
  hitRateValues,
  isoDate,
  plotRates,
  presetDefaultGranularity,
  presetRange,
  presetTsWindow,
  rangeDays,
  rateSeries,
  sumCounts,
} from "../src/features/usage/usage-controls";
import { SERIES_COLORS } from "../src/lib/category-colors";

const point = (over: Partial<UsageSeriesPoint>): UsageSeriesPoint => ({
  bucket: "2026-08-20",
  cacheRead: 0,
  cacheWrite: 0,
  output: 0,
  total: 0,
  cost: null,
  requests: 0,
  completed: 0,
  denominator: 0,
  ...over,
});

describe("presetRange / presetTsWindow / rangeDays", () => {
  it("a calendar preset ends today and spans its day count inclusively", () => {
    const today = new Date(2026, 7, 20); // 2026-08-20 local
    expect(presetRange("7d", today)).toEqual({ from: "2026-08-14", to: "2026-08-20" });
    expect(presetRange("30d", today)).toEqual({ from: "2026-07-22", to: "2026-08-20" });
    expect(presetRange("90d", today)).toEqual({ from: "2026-05-23", to: "2026-08-20" });
    expect(isoDate(today)).toBe("2026-08-20");
  });

  it("a trailing preset yields instant bounds plus the local dates they span", () => {
    const now = new Date(2026, 7, 20, 0, 30); // 00:30 local: the trailing day crosses midnight
    const hour = presetTsWindow("1h", now);
    expect(hour.toTs).toBe(now.toISOString());
    expect(Date.parse(hour.toTs) - Date.parse(hour.fromTs)).toBe(3_600_000);
    expect(hour.to).toBe("2026-08-20");
    expect(hour.from).toBe("2026-08-19");
    const day = presetTsWindow("1d", now);
    expect(Date.parse(day.toTs) - Date.parse(day.fromTs)).toBe(86_400_000);
    expect(day.from).toBe("2026-08-19");
  });

  it("rangeDays counts both ends; nonsense ranges count as 1", () => {
    expect(rangeDays("2026-08-14", "2026-08-20")).toBe(7);
    expect(rangeDays("2026-08-20", "2026-08-20")).toBe(1);
    expect(rangeDays("2026-08-21", "2026-08-20")).toBe(1);
    expect(rangeDays("oops", "2026-08-20")).toBe(1);
  });
});

describe("the range picks the precision (there is no precision control)", () => {
  /**
   * How many buckets a preset's own window produces at its derived precision.
   * The server rejects anything over 500 (usage-service caps the zero-fill
   * skeleton), and with the precision control gone the page has to be
   * incapable of asking for a rejected combination in the first place.
   */
  const MAX_BUCKETS = 500;
  const buckets: Record<string, number> = {
    "1h": 61, // 60 minutes, both ends inclusive
    "1d": 25, // 24 hours, both ends inclusive
    "7d": 7,
    "30d": 30,
    "90d": 90,
  };

  it("each preset derives exactly one precision", () => {
    expect(presetDefaultGranularity("1h", 1)).toBe("minute");
    expect(presetDefaultGranularity("1d", 1)).toBe("hour");
    expect(presetDefaultGranularity("7d", 7)).toBe("day");
    expect(presetDefaultGranularity("30d", 30)).toBe("day");
    expect(presetDefaultGranularity("90d", 90)).toBe("day");
  });

  it("a custom range scales with its length: day, then week, then month", () => {
    expect(presetDefaultGranularity("custom", 1)).toBe("day");
    expect(presetDefaultGranularity("custom", 92)).toBe("day");
    expect(presetDefaultGranularity("custom", 93)).toBe("week");
    expect(presetDefaultGranularity("custom", 190)).toBe("week");
    expect(presetDefaultGranularity("custom", 191)).toBe("month");
    expect(defaultGranularity(365)).toBe("month");
  });

  it("no preset can ask the server for more buckets than it will return", () => {
    for (const [preset, count] of Object.entries(buckets)) {
      expect(count).toBeLessThanOrEqual(MAX_BUCKETS);
    }
    // Custom ranges are bounded by their own derivation: day only up to a
    // quarter (92 buckets), then week (a year is 53), then month.
    expect(Math.ceil(92 / 1)).toBeLessThanOrEqual(MAX_BUCKETS);
    expect(Math.ceil(190 / 7) + 1).toBeLessThanOrEqual(MAX_BUCKETS);
    expect(Math.ceil((365 * 5) / 30)).toBeLessThanOrEqual(MAX_BUCKETS);
  });

  it("only the trailing presets reach the precisions that need timestamp bounds", () => {
    // minute always, and hour when a window is given, are enumerated between
    // instants server-side — so exactly the two presets that send fromTs/toTs.
    const needsWindow = (g: string) => g === "minute" || g === "hour";
    expect(needsWindow(presetDefaultGranularity("1h", 1))).toBe(true);
    expect(needsWindow(presetDefaultGranularity("1d", 1))).toBe(true);
    for (const [preset, days] of [
      ["7d", 7],
      ["30d", 30],
      ["90d", 90],
      ["custom", 45],
      ["custom", 400],
    ] as const) {
      expect(needsWindow(presetDefaultGranularity(preset, days))).toBe(false);
    }
  });
});

describe("bucket labels", () => {
  it("axis form is short; bubble form is the full key with a minute/hour key's T opened up", () => {
    expect(bucketAxisLabel("minute", "2026-08-20T09:05")).toBe("09:05");
    expect(bucketAxisLabel("hour", "2026-08-20T09:00")).toBe("09:00");
    expect(bucketAxisLabel("day", "2026-08-20")).toBe("08-20");
    expect(bucketAxisLabel("week", "2026-08-17")).toBe("08-17");
    expect(bucketAxisLabel("month", "2026-08")).toBe("2026-08");
    expect(bucketFullLabel("minute", "2026-08-20T09:05")).toBe("2026-08-20 09:05");
    expect(bucketFullLabel("week", "2026-08-17")).toBe("2026-08-17");
  });
});

describe("foldEntitySeries", () => {
  /** An entity's counts, spelled out per bucket: requests, of which `completed`, over `denominator` rated ones. */
  const e = (label: string, requests: number[], completed = requests, denominator = requests) => ({
    label,
    requests,
    completed,
    denominator,
  });

  it("top entities keep their own series; a tail of two or more folds into one summed, counted tail", () => {
    const folded = foldEntitySeries(
      [
        e("a", [5, 5]),
        e("b", [4, 0]),
        e("c", [1, 2]),
        e("d", [1, 1]),
        e("e", [1, 0]),
        e("f", [0, 1]),
      ],
      (n) => `other:${n}`,
      4,
    );
    expect(folded.map((x) => x.label)).toEqual(["a", "b", "c", "d", "other:2"]);
    // The label carries the fold count, so the chart never implies the head is everything.
    expect(folded[4]).toEqual({
      label: "other:2",
      requests: [1, 1],
      completed: [1, 1],
      denominator: [1, 1],
      other: true,
    });
  });

  it("the tail sums success counts too, so its line is the combined rate rather than one entity's", () => {
    const folded = foldEntitySeries(
      [
        e("a", [1]),
        e("b", [1]),
        e("c", [1]),
        e("d", [1]),
        e("e", [4], [1], [4]),
        e("f", [4], [3], [4]),
      ],
      (n) => `other:${n}`,
      4,
    );
    expect(folded[4]!.completed).toEqual([4]);
    expect(folded[4]!.denominator).toEqual([8]);
    expect(rateSeries(folded[4]!)).toEqual([50]);
  });

  it("a tail of exactly one keeps its name (a mystery bucket of one is worse than a fifth label)", () => {
    const folded = foldEntitySeries(
      [e("a", [1]), e("b", [1]), e("c", [1]), e("d", [1]), e("e", [2])],
      (n) => `other:${n}`,
      4,
    );
    expect(folded[4]).toEqual({
      label: "e",
      requests: [2],
      completed: [2],
      denominator: [2],
      other: true,
    });
  });

  it("no tail, no fold", () => {
    expect(foldEntitySeries([e("a", [1])], (n) => `other:${n}`, 4)).toEqual([
      { label: "a", requests: [1], completed: [1], denominator: [1] },
    ]);
    expect(foldEntitySeries([], (n) => `other:${n}`, 4)).toEqual([]);
  });

  it("by default keeps as many named series as the palette has colours, and folds the rest", () => {
    const many = Array.from({ length: SERIES_COLORS.length + 3 }, (_, i) => e(`e${i}`, [1]));
    const folded = foldEntitySeries(many, (n) => `other:${n}`);
    expect(folded.filter((series) => !series.other)).toHaveLength(SERIES_COLORS.length);
    expect(folded.at(-1)).toMatchObject({ label: "other:3", other: true });
  });
});

describe("sumCounts", () => {
  it("adds the drawn series column by column: the stack's height and the counts behind its combined rate", () => {
    const totals = sumCounts([
      { label: "a", requests: [2, 0], completed: [1, 0], denominator: [2, 0] },
      { label: "b", requests: [1, 3], completed: [1, 3], denominator: [1, 3] },
    ]);
    expect(totals).toEqual({ requests: [3, 3], completed: [2, 3], denominator: [3, 3] });
    expect(rateSeries(totals)).toEqual([(2 / 3) * 100, 100]);
  });

  it("no series at all sums to nothing (an empty chart, not a crash)", () => {
    expect(sumCounts([])).toEqual({ requests: [], completed: [], denominator: [] });
  });
});

describe("rate values", () => {
  it("per-entity success rate is percent of the non-aborted denominator", () => {
    expect(rateSeries({ completed: [3, 1, 0], denominator: [4, 1, 2] })).toEqual([75, 100, 0]);
  });

  it("a bucket with nothing to rate has no rate at all — null, which is neither the 0 of 'failed everything' nor a number the table may print", () => {
    expect(rateSeries({ completed: [0, 2, 0], denominator: [0, 2, 0] })).toEqual([null, 100, null]);
    // A real 0 survives as 0: requests were made and every one of them failed.
    expect(rateSeries({ completed: [0], denominator: [3] })).toEqual([0]);
  });

  it("cache hit rate is percent of read/(read+write); a bucket with no cache traffic has no rate either", () => {
    expect(
      hitRateValues([
        point({ cacheRead: 3, cacheWrite: 1 }),
        point({}),
        point({ cacheRead: 0, cacheWrite: 5 }),
      ]),
    ).toEqual([75, null, 0]);
  });

  it("plotRates gives every bucket a height so the stroke stays continuous, absent rates at the top of the axis", () => {
    expect(plotRates([75, null, 0])).toEqual([75, 100, 0]);
    // Drawing at 100 and reading 0 are different questions: a rated 0 is not lifted.
    expect(plotRates(rateSeries({ completed: [0, 0], denominator: [0, 4] }))).toEqual([100, 0]);
  });
});

describe("compactSeries", () => {
  const at = (bucket: string, over: Partial<UsageSeriesPoint> = {}) =>
    point({ bucket, requests: 1, total: 10, ...over });

  it("drops the buckets that recorded nothing and keeps the rest in order, with where each one sat", () => {
    const c = compactSeries([at("d1"), point({ bucket: "d2" }), at("d3")]);
    expect(c.points.map((p) => p.bucket)).toEqual(["d1", "d3"]);
    expect(c.kept).toEqual([0, 2]);
  });

  it("a request that spent no tokens keeps its bucket; only a bucket with neither is empty", () => {
    const c = compactSeries([
      point({ bucket: "d1", requests: 1, total: 0 }),
      point({ bucket: "d2", requests: 0, total: 5 }),
      point({ bucket: "d3" }),
    ]);
    expect(c.points.map((p) => p.bucket)).toEqual(["d1", "d2"]);
    expect(c.kept).toEqual([0, 1]);
  });

  it("a bucket only one entity ran in is not empty: the bucket is what counts, never one entity's share of it", () => {
    // d2 holds a single request from one entity; the others were idle in it.
    const c = compactSeries([
      at("d1"),
      at("d2", { requests: 1, total: 4 }),
      point({ bucket: "d3" }),
    ]);
    expect(c.points.map((p) => p.bucket)).toEqual(["d1", "d2"]);
  });

  it("breaks mark the drawn point each skip follows, however many buckets it swallowed", () => {
    const c = compactSeries([
      at("d1"),
      point({ bucket: "d2" }),
      point({ bucket: "d3" }),
      at("d4"),
      at("d5"),
      point({ bucket: "d6" }),
      at("d7"),
    ]);
    expect(c.points.map((p) => p.bucket)).toEqual(["d1", "d4", "d5", "d7"]);
    expect(c.breaks).toEqual([0, 2]);
    expect(c.kept).toEqual([0, 3, 4, 6]);
  });

  it("empty buckets before the first point or after the last shorten the axis without breaking it", () => {
    const c = compactSeries([point({ bucket: "d1" }), at("d2"), point({ bucket: "d3" })]);
    expect(c.points.map((p) => p.bucket)).toEqual(["d2"]);
    expect(c.breaks).toEqual([]);
    expect(c.kept).toEqual([1]);
  });

  it("a range that recorded nothing compacts to nothing (the charts show their empty state, not a flat zero line)", () => {
    expect(compactSeries([point({}), point({})])).toEqual({ points: [], kept: [], breaks: [] });
    expect(compactSeries([])).toEqual({ points: [], kept: [], breaks: [] });
  });

  it("nothing to drop leaves the series and its axis exactly as they came", () => {
    const full = [at("d1"), at("d2")];
    const c = compactSeries(full);
    expect(c.points).toEqual(full);
    expect(c.breaks).toEqual([]);
    expect(c.kept).toEqual([0, 1]);
  });
});

describe("compactCounts (per-entity alignment across the compaction)", () => {
  // Five buckets; the server sends every entity one value per bucket, aligned
  // with the series. d2 and d4 recorded nothing at all.
  const series = [
    point({ bucket: "d1", requests: 2, total: 20 }),
    point({ bucket: "d2" }),
    point({ bucket: "d3", requests: 3, total: 30 }),
    point({ bucket: "d4" }),
    point({ bucket: "d5", requests: 1, total: 10 }),
  ];
  const entity = {
    requests: [2, 0, 1, 0, 0],
    completed: [1, 0, 1, 0, 0],
    denominator: [2, 0, 1, 0, 0],
  };

  it("takes exactly the kept positions, so a value stays with the bucket it was recorded in", () => {
    const { points, kept } = compactSeries(series);
    const compacted = compactCounts(entity, kept);
    expect(points.map((p) => p.bucket)).toEqual(["d1", "d3", "d5"]);
    expect(compacted).toEqual({
      requests: [2, 1, 0],
      completed: [1, 1, 0],
      denominator: [2, 1, 0],
    });
    // The invariant the per-entity series are built on, asserted by bucket key
    // rather than by position: value[i] after the compaction is still the value
    // the server sent for points[i].bucket.
    points.forEach((p, i) => {
      const origin = series.findIndex((q) => q.bucket === p.bucket);
      expect(compacted.requests[i]).toBe(entity.requests[origin]);
      expect(compacted.completed[i]).toBe(entity.completed[origin]);
      expect(compacted.denominator[i]).toBe(entity.denominator[origin]);
    });
  });

  it("an entity idle in a kept bucket keeps its zero there, which is what makes it a dash and not a missing column", () => {
    const { kept } = compactSeries(series);
    const idle = compactCounts(
      { requests: [0, 0, 0, 0, 1], completed: [0, 0, 0, 0, 1], denominator: [0, 0, 0, 0, 1] },
      kept,
    );
    expect(idle.requests).toEqual([0, 0, 1]);
    expect(rateSeries(idle)).toEqual([null, null, 100]);
  });

  it("a short or missing array reads as zero rather than undefined (a chart never plots a hole it cannot explain)", () => {
    expect(compactCounts({ requests: [5], completed: [], denominator: [] }, [0, 2])).toEqual({
      requests: [5, 0],
      completed: [0, 0],
      denominator: [0, 0],
    });
  });
});