refactor(outcome): lift the write-outcome classifier out of the import panel

The rule that a write which wrote nothing must not read as a success was
scoped to the import panel. Provider syncs need the same rule, so the
classifier moves to src/lib/outcome/written-outcome.ts and the tick plus the
success colour move to one presentation component the whole tree renders
through. Adds the sync shape: a run reports what it imported and whether any
part of it failed, and the outcome is resolved from both.
This commit is contained in:
Marc-André Bombeck committed 2026-07-27 22:43:27 +02:00
1 parent 60c30e1e3a
commit 52288b7f77
9 files changed
+288 -157

No files matched your search

@@ -8,9 +8,9 @@
* the thing that has to be right is the sentence at the end of the run.
*
* The rules are the ones the settings import panel already follows, reused
* rather than restated: `classifyImportOutcome` decides the tone from the
* rather than restated: `classifyWrittenOutcome` decides the tone from the
* counts, so an import that wrote nothing can never carry the success tick,
* and `ImportOutcomeLine` owns the tick and the success colour. The skips are
* and `WrittenOutcomeLine` owns the tick and the success colour. The skips are
* grouped by reason with a count, because a file that trips one rule trips it
* on every row and a per-row list is the same sentence a hundred times.
*
@@ -18,11 +18,11 @@
* cards; the medication intake import is the third import surface and it now
* answers the same way.
*/
import { WrittenOutcomeLine } from "@/components/outcome/written-outcome-line";
import {
classifyImportOutcome,
type ImportOutcome,
} from "@/components/settings/import-panel/import-result-state";
import { ImportOutcomeLine } from "@/components/settings/import-panel/import-result-view";
classifyWrittenOutcome,
type WrittenOutcome,
} from "@/lib/outcome/written-outcome";
import { useTranslations } from "@/lib/i18n/context";
/** A skip group exactly as the import job reports it. */
@@ -132,7 +132,7 @@ export function IntakeImportResultView({
);
}
const outcome: ImportOutcome = classifyImportOutcome({
const outcome: WrittenOutcome = classifyWrittenOutcome({
written: result.imported,
skipped: result.skipped,
});
@@ -153,7 +153,7 @@ export function IntakeImportResultView({
return (
<div data-testid="intake-import-result" className="space-y-1.5">
<ImportOutcomeLine
<WrittenOutcomeLine
outcome={outcome}
message={message}
testId="intake-import-outcome"
+33
View File
@@ -0,0 +1,33 @@
"use client";
import { toast } from "sonner";
import type { WrittenOutcome } from "@/lib/outcome/written-outcome";
/**
* The toast twin of `WrittenOutcomeLine`: one mapping from a written outcome
* to the toast variant that reports it.
*
* `toast.success` lives here and is reached only through the `success` key, so
* a surface that reports a write cannot raise a green toast for a run that
* wrote nothing. `empty` uses the neutral variant rather than the success one
* — "nothing to write" is an honest non-event, not an achievement.
*/
export function toastWrittenOutcome(
outcome: WrittenOutcome,
message: string,
): void {
switch (outcome) {
case "success":
toast.success(message);
return;
case "partial":
toast.warning(message);
return;
case "failed":
toast.error(message);
return;
case "empty":
toast.info(message);
}
}
@@ -0,0 +1,57 @@
"use client";
import { AlertCircle, CheckCircle2, Info, TriangleAlert } from "lucide-react";
import type { LucideIcon } from "lucide-react";
import type { WrittenOutcome } from "@/lib/outcome/written-outcome";
/**
* The one mapping from a written outcome to how it looks.
*
* `CheckCircle2` and `text-success` appear on the `success` key and nowhere
* else in this file, so no future edit can attach a tick to a run that wrote
* nothing. Every import card and every provider-sync card renders its result
* line through here; `src/__tests__/success-affordance-guard.test.ts` holds
* that line.
*/
const OUTCOME_PRESENTATION: Record<
WrittenOutcome,
{ Icon: LucideIcon; className: string }
> = {
success: { Icon: CheckCircle2, className: "text-success" },
partial: { Icon: TriangleAlert, className: "text-warning" },
failed: { Icon: AlertCircle, className: "text-destructive" },
empty: { Icon: Info, className: "text-muted-foreground" },
};
/**
* The headline line of a write result. Sits inside the caller's existing
* `aria-live` region where there is one, so the outcome is announced as it
* lands; a `failed` or `partial` line carries `role="alert"` itself, because
* a result that did not write is the case a user must not scroll past.
*/
export function WrittenOutcomeLine({
outcome,
message,
testId,
}: {
outcome: WrittenOutcome;
message: string;
testId: string;
}) {
const { Icon, className } = OUTCOME_PRESENTATION[outcome];
return (
<p
data-testid={testId}
data-outcome={outcome}
role={outcome === "failed" || outcome === "partial" ? "alert" : "status"}
className="text-foreground flex items-start gap-2 text-xs"
>
<Icon
className={`${className} mt-0.5 h-3.5 w-3.5 shrink-0`}
aria-hidden="true"
/>
<span>{message}</span>
</p>
);
}
@@ -1,94 +0,0 @@
/**
* #640 — an import that wrote nothing must never read as a success.
*
* The reported failure was not the parser refusing rows; it was the card
* answering that refusal with a green tick, which is what turned a
* recoverable problem into a silent one. These pin the classifier that both
* import cards render from, and the structural guard that keeps the success
* affordance attached to the success outcome alone lives alongside in
* `import-result-guard.test.ts`.
*/
import { describe, it, expect } from "vitest";
import {
classifyImportOutcome,
groupSkipReasons,
} from "../import-result-state";
describe("classifyImportOutcome", () => {
it("calls the reported production result a failure", () => {
// The audit envelope from the report: 1 597 rows in, nothing written.
expect(classifyImportOutcome({ written: 0, skipped: 1597 })).toBe("failed");
});
it("calls a file with no data rows empty, not a success", () => {
expect(classifyImportOutcome({ written: 0, skipped: 0 })).toBe("empty");
});
it("calls a mixed result partial", () => {
expect(classifyImportOutcome({ written: 3, skipped: 2 })).toBe("partial");
});
it("calls a clean result a success", () => {
expect(classifyImportOutcome({ written: 5, skipped: 0 })).toBe("success");
});
it("never reaches success while nothing was written", () => {
for (let written = 0; written <= 4; written++) {
for (let skipped = 0; skipped <= 4; skipped++) {
const outcome = classifyImportOutcome({ written, skipped });
if (written === 0) {
expect(outcome).not.toBe("success");
expect(outcome).not.toBe("partial");
}
if (outcome === "success") {
expect(written).toBeGreaterThan(0);
expect(skipped).toBe(0);
}
}
}
});
});
describe("groupSkipReasons", () => {
it("collapses a repeated reason to one entry with a count", () => {
const rows = Array.from({ length: 1597 }, (_, i) => ({
line: i + 2,
status: "skipped",
reason: "invalid_glucose_context",
}));
expect(groupSkipReasons(rows)).toEqual([
{ reason: "invalid_glucose_context", count: 1597 },
]);
});
it("ignores rows that were written", () => {
expect(
groupSkipReasons([
{ line: 2, status: "inserted" },
{ line: 3, status: "updated" },
{ line: 4, status: "skipped", reason: "unknown_unit" },
]),
).toEqual([{ reason: "unknown_unit", count: 1 }]);
});
it("orders by count descending, then by reason", () => {
const rows = [
{ line: 2, status: "skipped", reason: "unknown_unit" },
{ line: 3, status: "skipped", reason: "duplicate" },
{ line: 4, status: "skipped", reason: "duplicate" },
{ line: 5, status: "skipped", reason: "notes_too_long" },
];
expect(groupSkipReasons(rows)).toEqual([
{ reason: "duplicate", count: 2 },
{ reason: "notes_too_long", count: 1 },
{ reason: "unknown_unit", count: 1 },
]);
});
it("buckets a skipped row that carries no reason", () => {
expect(groupSkipReasons([{ line: 2, status: "skipped" }])).toEqual([
{ reason: "unknown", count: 1 },
]);
});
});
@@ -11,8 +11,8 @@ import { useTranslations } from "@/lib/i18n/context";
import { cn } from "@/lib/utils";
import { apiFetchRaw, apiGet } from "@/lib/api/api-fetch";
import { ImportCardShell } from "./import-card-shell";
import { classifyImportOutcome } from "./import-result-state";
import { ImportOutcomeLine } from "./import-result-view";
import { WrittenOutcomeLine } from "@/components/outcome/written-outcome-line";
import { classifyWrittenOutcome } from "@/lib/outcome/written-outcome";
/** Terminal states the status poll stops on. */
const TERMINAL_STATES: readonly string[] = ["done", "failed"];
@@ -239,8 +239,8 @@ export function AppleHealthImportCard() {
</div>
)}
{isDone && (
<ImportOutcomeLine
outcome={classifyImportOutcome({
<WrittenOutcomeLine
outcome={classifyWrittenOutcome({
written: status?.result?.totals?.rowsUpserted ?? 0,
// The clinical count is a documented, deliberate exclusion
// (electrocardiograms, lab documents), not a refused row — it
@@ -1,72 +0,0 @@
/**
* Import result classification — the one place that decides whether an
* import reads as a success.
*
* A per-row importer answers HTTP 200 for a file where every single row was
* refused; the transport succeeded, the import did not. Rendering that as a
* green tick is how a self-hoster's 1 597-reading sensor export could write
* nothing and still look finished. So the counts, not the status code, pick
* the state:
*
* - nothing accepted, nothing skipped → `empty` (the file carried no data)
* - nothing accepted, rows skipped → `failed` (never a success tone)
* - some accepted, some skipped → `partial` (a warning, not a tick)
* - all accepted → `success`
*
* Both import cards render from this, and `import-result-state.test.ts` pins
* the invariant that `success` is unreachable while `written === 0`.
*/
export type ImportOutcome = "empty" | "failed" | "partial" | "success";
export interface ImportCounts {
/** Rows that reached the database — inserted + updated. */
written: number;
/** Rows the importer refused, for any reason. */
skipped: number;
}
export function classifyImportOutcome({
written,
skipped,
}: ImportCounts): ImportOutcome {
if (written <= 0) return skipped > 0 ? "failed" : "empty";
return skipped > 0 ? "partial" : "success";
}
export interface SkipReasonGroup {
/** The machine-readable reason as the route reported it. */
reason: string;
count: number;
}
/** A row of the per-row envelope, narrowed to what the grouping needs. */
export interface ImportRowResult {
line: number;
status: string;
reason?: string;
}
const UNKNOWN_REASON = "unknown";
/**
* Collapse the per-row envelope into one entry per skip reason.
*
* A sensor export that trips one validation trips it on every row, so the
* raw list is the same sentence a few thousand times. Grouping turns "scroll
* fifty identical lines" into one fact with a count. Ordered by count
* descending, then by reason, so the same result always renders the same way.
*/
export function groupSkipReasons(
rows: readonly ImportRowResult[],
): SkipReasonGroup[] {
const counts = new Map<string, number>();
for (const row of rows) {
if (row.status !== "skipped") continue;
const reason = row.reason ?? UNKNOWN_REASON;
counts.set(reason, (counts.get(reason) ?? 0) + 1);
}
return [...counts.entries()]
.map(([reason, count]) => ({ reason, count }))
.sort((a, b) => b.count - a.count || a.reason.localeCompare(b.reason));
}
@@ -1,61 +1,12 @@
"use client";
import { AlertCircle, CheckCircle2, Info, TriangleAlert } from "lucide-react";
import type { LucideIcon } from "lucide-react";
import { WrittenOutcomeLine } from "@/components/outcome/written-outcome-line";
import { useTranslations } from "@/lib/i18n/context";
import {
classifyImportOutcome,
classifyWrittenOutcome,
groupSkipReasons,
type ImportOutcome,
type ImportRowResult,
} from "./import-result-state";
/**
* The one mapping from an import outcome to how it looks.
*
* `CheckCircle2` and `text-success` appear exactly once in the import panel,
* on the `success` key, so no future edit can attach a tick to a result that
* wrote nothing. `import-result-guard.test.ts` holds that line.
*/
const OUTCOME_PRESENTATION: Record<
ImportOutcome,
{ Icon: LucideIcon; className: string }
> = {
success: { Icon: CheckCircle2, className: "text-success" },
partial: { Icon: TriangleAlert, className: "text-warning" },
failed: { Icon: AlertCircle, className: "text-destructive" },
empty: { Icon: Info, className: "text-muted-foreground" },
};
/**
* The headline line of an import result. Sits inside each card's existing
* `aria-live="polite"` region, so the outcome is announced as it lands.
*/
export function ImportOutcomeLine({
outcome,
message,
testId,
}: {
outcome: ImportOutcome;
message: string;
testId: string;
}) {
const { Icon, className } = OUTCOME_PRESENTATION[outcome];
return (
<p
data-testid={testId}
data-outcome={outcome}
className="text-foreground flex items-start gap-2 text-xs"
>
<Icon
className={`${className} mt-0.5 h-3.5 w-3.5 shrink-0`}
aria-hidden="true"
/>
<span>{message}</span>
</p>
);
}
type WrittenRowResult,
} from "@/lib/outcome/written-outcome";
export interface CsvImportResult {
inserted: number;
@@ -63,7 +14,7 @@ export interface CsvImportResult {
skipped: number;
total: number;
dryRun: boolean;
rows: ImportRowResult[];
rows: WrittenRowResult[];
}
/**
@@ -118,7 +69,7 @@ export function CsvImportResultView({ result }: { result: CsvImportResult }) {
const labelFor = useSkipReasonLabel();
const written = result.inserted + result.updated;
const outcome = classifyImportOutcome({ written, skipped: result.skipped });
const outcome = classifyWrittenOutcome({ written, skipped: result.skipped });
const groups = groupSkipReasons(result.rows);
const skippedRows = result.rows.filter((row) => row.status === "skipped");
@@ -162,7 +113,7 @@ export function CsvImportResultView({ result }: { result: CsvImportResult }) {
return (
<div data-testid="import-csv-result" className="space-y-1.5">
<ImportOutcomeLine
<WrittenOutcomeLine
outcome={outcome}
message={message}
testId="import-csv-outcome"
@@ -12,8 +12,8 @@ import { apiFetchRaw } from "@/lib/api/api-fetch";
import { ImportCardShell } from "./import-card-shell";
import { MAX_PASTE_CHARS } from "./constants";
import { EXAMPLE_IMPORT, parseImportJson } from "./import-examples";
import { classifyImportOutcome } from "./import-result-state";
import { ImportOutcomeLine } from "./import-result-view";
import { WrittenOutcomeLine } from "@/components/outcome/written-outcome-line";
import { classifyWrittenOutcome } from "@/lib/outcome/written-outcome";
interface JsonImportResult {
measurements: number;
@@ -28,7 +28,7 @@ export function JsonImportCard() {
// concept count envelope, so a payload where every entry was refused used
// to render the success tick. The counts decide the tone.
const jsonOutcome = (r: JsonImportResult) =>
classifyImportOutcome({
classifyWrittenOutcome({
written: r.measurements + r.moodEntries,
skipped: r.skipped,
});
@@ -191,7 +191,7 @@ export function JsonImportCard() {
<div aria-live="polite" className="space-y-2">
{result && (
<ImportOutcomeLine
<WrittenOutcomeLine
outcome={jsonOutcome(result)}
message={jsonMessage(result)}
testId="import-json-result"