Files
HealthLog/src/__tests__/measurement-write-tail-guard.test.ts
T

230 lines
10 KiB
TypeScript

/**
* Every place that writes `Measurement` rows either runs the shared
* post-write tail or says here why it does not.
*
* Two readers hang off every measurement write: the rollup buckets the write
* dirtied, and the cached status assessments of the types it touched. The
* shared tail (`afterMeasurementMutation`) runs both. Several write paths
* refreshed the rollups by hand and never re-warmed the assessments (the MCP
* writes, the Telegram reply, both importers), so a reading logged there kept
* the day's old assessment until the nightly pass. This guard freezes the set
* of write sites: a new one fails until it is listed with its tail.
*
* A tripwire, not a proof: it cannot tell whether a listed reason is still
* true, only that the set did not change without someone editing this file.
*/
import { describe, it, expect } from "vitest";
import { readFileSync } from "node:fs";
import { join } from "node:path";
import { walkSourceFiles } from "./helpers/source-files";
const SRC = join(process.cwd(), "src");
/**
* `prisma.measurement.create(`, `tx.measurement.deleteMany(`, … Whitespace
* and line breaks between the parts are tolerated so a formatter reflow does
* not hide a site.
*/
const WRITE_RE =
/\.\s*measurement\s*\.\s*(?:create|createMany|createManyAndReturn|upsert|update|updateMany|delete|deleteMany)\s*\(/g;
/** Runs `afterMeasurementMutation` on the rows it wrote. */
const TAIL = "runs afterMeasurementMutation";
/**
* Writes here; the module named runs `afterMeasurementMutation` on the same
* rows (a service split into stages, whose write and tail are siblings).
*/
const TAIL_VIA_PREFIX = "runs afterMeasurementMutation via ";
const TAIL_VIA = (file: string) => `${TAIL_VIA_PREFIX}${file}`;
/**
* Runs the provider write step (`integrations/sync-kit/after-write.ts`),
* which is `afterMeasurementMutation` plus the arrivals and, where asked, the
* dashboard snapshot.
*/
const PROVIDER_TAIL = "runs afterProviderWrite";
/**
* Every file with a measurement write, and how it keeps the two readers
* current. A file listed here must still contain a write (a stale entry
* fails too).
*/
const WRITE_SITES: Record<string, string> = {
"lib/import/csv-write.ts": TAIL,
"lib/import/json/measurements.ts": TAIL_VIA("lib/import/json/run.ts"),
"app/api/measurements/[id]/route.ts": TAIL,
"app/api/measurements/bulk-delete/route.ts": TAIL,
"app/api/measurements/by-external-ids/route.ts": TAIL,
"app/api/measurements/restore/route.ts": TAIL,
"lib/measurements/batch-ingest/write-measurements.ts": TAIL_VIA(
"lib/measurements/batch-ingest/tail.ts",
),
"lib/measurements/create/create-readings.ts": TAIL,
"app/api/mental-health/assessments/route.ts": TAIL,
"lib/insights/score-row.ts": TAIL,
"lib/mcp/writes.ts": TAIL,
"lib/measurements/create-from-telegram.ts": TAIL,
"lib/whoop/sync-body.ts": TAIL,
"lib/whoop/webhook-handler.ts": TAIL,
// Retiring the rows of Oura sleep periods the person rejected or deleted.
"lib/oura/sync.ts": TAIL,
// Retiring the equivalent-distance rows earlier Oura syncs wrote.
"lib/oura/retire-distance.ts": TAIL,
// Integration syncs: each collects the (type, day) pairs it touched and
// runs the provider write step over them.
"lib/fitbit/sync-core.ts": PROVIDER_TAIL,
"lib/google-health/sync-core.ts": PROVIDER_TAIL,
"lib/nightscout/sync.ts": PROVIDER_TAIL,
"lib/withings/sync.ts": PROVIDER_TAIL,
"lib/oura/sync-heart-rate.ts":
"collects the days each heart-rate page touched; refolds them and re-warms the type once per window",
"lib/withings/sync-activity.ts":
"refolds the touched days (and the day a moved row left) and re-warms the touched types",
"lib/withings/sync-ecg.ts":
"refolds the touched days and re-warms the touched types at the end of the sync",
// The reconcile primitive writes one row inside the caller's transaction;
// its callers (Polar, Oura, WHOOP, the Apple export import) collect the
// verdicts' dirty identities and run the tail once per batch.
"lib/measurements/reconcile-external-measurement.ts":
"a primitive; every caller runs the tail over the verdicts' dirty identities",
"lib/measurements/import-apple-health-export.ts":
"the import worker refolds the import's span and re-warms every imported type",
"lib/measurements/import-unchanged-rows.ts":
"the Apple export import's natural-key rescue, inside the import; its worker runs both legs once over the whole import",
"lib/import/health-connect/import.ts":
"the Health Connect import worker refolds the import's span and re-warms every imported type",
"lib/export/measurements-restore.ts":
"a restore replaces the whole record: it refolds the whole window and drops every per-user cache",
// Value-preserving reshapes: the same readings folded into daily or hourly
// rows. The rollups are refolded; the figures an assessment reads do not
// change, so re-warming would only re-bill the same text.
"lib/measurements/consolidate-daily-mean.ts":
"value-preserving consolidation; refolds the touched days",
"lib/measurements/consolidate-legacy-steps.ts":
"value-preserving consolidation; refolds the touched days",
"lib/measurements/drain-per-sample-cumulative.ts":
"value-preserving consolidation; refolds the touched days",
"lib/measurements/dense-intraday-hourly-rebuild.ts":
"value-preserving hourly fold; refolds the touched spans",
"lib/measurements/dense-intraday-retention.ts":
"value-preserving retention fold; refolds the touched days",
"lib/jobs/sleep-timeline-backfill.ts":
"one-shot re-stamp of stored sleep rows onto their timeline; refolds the touched days",
"lib/jobs/step-consolidation-repair.ts":
"one-shot restore of step rows an old consolidation removed; refolds the touched days",
"lib/sleep/sweep-stale-segments.ts":
"tombstones re-scored sleep segments inside a sync; the calling sync refolds the night",
// Writes that do not change a reading.
"lib/jobs/note-encryption-backfill.ts":
"encrypts the note column in place; no value, instant or type changes",
"lib/jobs/measurement-tombstone-cleanup.ts":
"hard-deletes rows that were already soft-deleted and read nowhere",
"lib/jobs/compaction-tombstone-purge.ts":
"hard-deletes compaction tombstones, rows already soft-deleted and read nowhere",
"lib/jobs/measurement-fold-repair.ts":
"corrects the value of a folded stats: mean in place, takes the window's live samples into it, and refolds the DAY rollup of a touched daily mean itself; no instant or type changes",
"lib/measurements/fold-constituents.ts":
"soft-deletes the samples a fold or the fold repair has just taken into a recomputed stats: mean, which accounts for them from then on",
};
function sourceFiles(): string[] {
return walkSourceFiles(SRC, { floor: 3000 })
.filter((p) => !p.startsWith("generated/"))
.filter((p) => !p.includes("__tests__"))
.filter((p) => !p.endsWith(".test.ts") && !p.endsWith(".test.tsx"))
.sort();
}
function writeCounts(): Map<string, number> {
const out = new Map<string, number>();
for (const rel of sourceFiles()) {
const matches = readFileSync(join(SRC, rel), "utf8").match(WRITE_RE);
if (matches && matches.length > 0) out.set(rel, matches.length);
}
return out;
}
describe("measurement write tail", () => {
const counts = writeCounts();
it("finds the write sites at all", () => {
// An empty match set would agree with any allowlist.
expect(counts.size).toBeGreaterThanOrEqual(30);
});
it("lists every file that writes measurements", () => {
const unlisted = [...counts.keys()].filter((f) => !(f in WRITE_SITES));
expect(
unlisted,
"a new measurement write site: run afterMeasurementMutation on the rows it writes, or list it here with the reason it does not",
).toEqual([]);
});
it("has no stale entries", () => {
const stale = Object.keys(WRITE_SITES).filter((f) => !counts.has(f));
expect(stale).toEqual([]);
});
it("the files that claim the shared tail call it", () => {
const claims = Object.entries(WRITE_SITES).filter(
([, reason]) => reason === TAIL || reason.startsWith(TAIL_VIA_PREFIX),
);
// Both shapes are in use; a set that lost either would check nothing.
expect(claims.filter(([, r]) => r === TAIL).length).toBeGreaterThan(5);
expect(
claims.filter(([, r]) => r.startsWith(TAIL_VIA_PREFIX)).length,
).toBeGreaterThan(0);
const missing = claims
.map(([file, reason]) =>
reason.startsWith(TAIL_VIA_PREFIX)
? reason.slice(TAIL_VIA_PREFIX.length)
: file,
)
.filter(
(file) =>
!/afterMeasurementMutation\s*\(/.test(
readFileSync(join(SRC, file), "utf8"),
),
);
expect(missing).toEqual([]);
});
it("the files that claim the provider write step call it", () => {
const claimed = Object.entries(WRITE_SITES)
.filter(([, reason]) => reason === PROVIDER_TAIL)
.map(([file]) => file);
expect(claimed.length).toBeGreaterThan(0);
const missing = claimed.filter(
(file) =>
!/afterProviderWrite\s*\(/.test(readFileSync(join(SRC, file), "utf8")),
);
expect(missing).toEqual([]);
});
it("the syncs that run both legs by hand call both", () => {
const handRolled = Object.entries(WRITE_SITES)
.filter(([, reason]) => reason.includes("re-warms"))
.map(([file]) => file)
// The two export importers leave both legs to their workers, which
// run them once over the whole import.
.filter(
(file) =>
file !== "lib/measurements/import-apple-health-export.ts" &&
file !== "lib/import/health-connect/import.ts",
);
expect(handRolled.length).toBeGreaterThan(0);
const missing = handRolled.filter((file) => {
const src = readFileSync(join(SRC, file), "utf8");
return !(
/recomputeBucketsFor(Measurement|Keys)|afterMeasurementMutation/.test(
src,
) &&
/invalidateStatusInsightsForTypes|afterMeasurementMutation/.test(src)
);
});
expect(missing).toEqual([]);
});
});