fix(webapp): describe how far a report metric fell

A fall's multiplier rounds to 0 or 1, so every drop rendered as "flat" — a metric
that collapsed from 100 to 5 read as unchanged. Measure the fall against the
baseline instead, and show a bare arrow when it collapsed to nothing.

Author: kathiekiwi

apps/webapp/app/presenters/v3/reports/report-layout.ts

@@ -518,12 +518,29 @@ function metricValue(metric: LayoutMetricInput, messages: ReportMessages): strin
     : fmtValue(metric.value, metric.unit);
 }
 
+/**
+ * How far a metric fell below its baseline: `undefined` when the fall doesn't round past 1×, and
+ * `null` when it collapsed to nothing and no multiplier can say it.
+ */
+function fallMultiplier(metric: LayoutMetricInput): number | null | undefined {
+  if (metric.normal === undefined || metric.normal <= 0) return undefined;
+  if (metric.value <= 0) return null;
+  const fall = Math.round(metric.normal / metric.value);
+  return fall > 1 ? fall : undefined;
+}
+
 /**
  * A metric's movement against its baseline. A multiplier only reads as movement once it rounds past
  * 1×; below that a metric with a baseline is flat, and one without has nothing to compare against.
  */
 function metricDelta(metric: LayoutMetricInput): LayoutDelta | undefined {
   const delta = metric.delta;
+  // A fall's own multiplier rounds to 0 or 1, so measure how far it fell instead.
+  if (delta?.dir === "down") {
+    const fall = fallMultiplier(metric);
+    if (fall === null) return { text: REPORT_GLYPH.down, dir: "down" };
+    if (fall !== undefined) return { text: `${REPORT_GLYPH.down} ${fall}×`, dir: "down" };
+  }
   if (delta && delta.mult !== undefined && delta.mult > 1 && delta.dir !== "flat") {
     return {
       text: `${delta.dir === "up" ? REPORT_GLYPH.up : REPORT_GLYPH.down} ${delta.mult}×`,

apps/webapp/test/reportMetricDelta.test.ts

@@ -0,0 +1,111 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildReportLayout,
+  type LayoutMetricInput,
+  type LayoutViewModel,
+  REPORT_GLYPH,
+} from "~/presenters/v3/reports/report-layout";
+import { reportMessages } from "~/presenters/v3/reports/report-messages";
+import { delta } from "~/presenters/v3/reports/report-view-model";
+
+const messages = reportMessages("health");
+
+function viewModel(overrides: Partial<LayoutViewModel> = {}): LayoutViewModel {
+  return {
+    title: "health",
+    scope: "prod",
+    period: "last 60m",
+    windowMinutes: 60,
+    summary: { severity: "warn", statements: [{ findingType: "flow", severity: "warn" }] },
+    findings: [{ type: "flow", severity: "warn", reason: "backlog_growing", metricIds: [] }],
+    metrics: [],
+    footer: [],
+    ...overrides,
+  };
+}
+
+/** Builds the metric the way the presenter does, so the rounded multiplier is the real one. */
+function metricRow(metric: Omit<LayoutMetricInput, "delta">) {
+  const withDelta: LayoutMetricInput = { ...metric, delta: delta(metric.value, metric.normal) };
+  const layout = buildReportLayout(
+    viewModel({
+      findings: [
+        { type: "flow", severity: "warn", reason: "backlog_growing", metricIds: [metric.id] },
+      ],
+      metrics: [withDelta],
+    }),
+    messages
+  );
+  const rows = [...(layout.hero?.metrics ?? []), ...layout.findings.flatMap((f) => f.metrics)];
+  const row = rows.find((r) => r.id === metric.id);
+  if (!row) throw new Error(`metric row ${metric.id} was not rendered`);
+  return row;
+}
+
+describe("report layout — a metric's movement against its baseline", () => {
+  it("renders a collapse as a down arrow with how far it fell", () => {
+    const row = metricRow({
+      id: "throughput",
+      value: 5,
+      normal: 100,
+      unit: "perMin",
+      severity: "crit",
+    });
+
+    expect(row.delta).toEqual({ text: `${REPORT_GLYPH.down} 20×`, dir: "down" });
+  });
+
+  it("renders a collapse to zero as a bare down arrow", () => {
+    const row = metricRow({
+      id: "throughput",
+      value: 0,
+      normal: 100,
+      unit: "perMin",
+      severity: "crit",
+    });
+
+    expect(row.delta).toEqual({ text: REPORT_GLYPH.down, dir: "down" });
+  });
+
+  it("leaves a dip that doesn't round past 1× reading as flat", () => {
+    const row = metricRow({
+      id: "throughput",
+      value: 95,
+      normal: 100,
+      unit: "perMin",
+      severity: "ok",
+    });
+
+    expect(row.delta).toEqual({ text: `${REPORT_GLYPH.flat} flat`, dir: "flat" });
+  });
+
+  it("still renders a rise with its multiplier", () => {
+    const row = metricRow({
+      id: "pending",
+      value: 1600,
+      normal: 100,
+      unit: "count",
+      severity: "crit",
+    });
+
+    expect(row.delta).toEqual({ text: `${REPORT_GLYPH.up} 16×`, dir: "up" });
+  });
+
+  it("still renders an unmoved metric as flat", () => {
+    const row = metricRow({
+      id: "pending",
+      value: 100,
+      normal: 100,
+      unit: "count",
+      severity: "ok",
+    });
+
+    expect(row.delta).toEqual({ text: `${REPORT_GLYPH.flat} flat`, dir: "flat" });
+  });
+
+  it("says nothing about a metric with no baseline", () => {
+    const row = metricRow({ id: "pending", value: 100, unit: "count", severity: "ok" });
+
+    expect(row.delta).toBeUndefined();
+  });
+});