# Code Quality + Documentation Audit — 2026-05-17

## Executive summary

The repo is in unusually good shape for its size: `tsc --noEmit` and `eslint`
both pass clean, there are zero `TODO`/`FIXME`/`XXX`/`HACK` markers in product
code, zero empty `catch` blocks outside one inline `<script>` fallback, and all
test files contain at least one `expect()`. The dominant debt is **archaeology
in comments** — 2 366 `v1.4.x` version-tag references across 200+ files, plus
244 wave/phase markers (`W5 reconcile (Code-H2)`, `IW-B`, `phase B8`). These
read like commit messages inlined into the source and will only get worse with
each release. The other three real wins are (1) deleting the 7-file
`getXSystemPrompt` / `getXUserPrompt` boilerplate in `src/lib/ai/prompts/`,
(2) removing the dead `SESSION_SECRET` env contract, and (3) closing the
JSDoc gap on `src/lib/**` exports (171/535 missing). Recommended order:
F-1 first (low-risk additive cleanup, biggest readability win), then F-2 and
F-9 in the same release, then the long-tail items.

## Findings — prioritized

### F-1: Version-tagged inline comments have become source-control archaeology

**Severity**: high
**Category**: comment debt
**File(s)**: `src/proxy.ts:28,32,36,50,179,190`, `src/app/page.tsx:85,93,99,109,201,207,217,253,259,272,281,288,307,328,353,396,401,539,564,589,675,890,921,935,1196,1214,1225`, `src/app/api/analytics/route.ts:36,55,67,...` (47 hits), `src/components/charts/health-chart.tsx` (46 hits), `src/lib/ai/schema.ts:5,28,32,52,55,...` (29 hits), and 30 other files
**What's wrong**: 2 366 inline references to `v1.4.x` plus 244 markers
shaped like `// v1.4.22 W5 reconcile (Sec-MED-2) — ...` or
`// v1.4.34 IW-B — ...`. They were useful while the release was in
flight, but they now narrate the commit history inside the source. A
reader of `dashboard-layout.ts:288` doesn't care that the comparison
baseline shipped in `v1.4.16 phase B8`; they want to know what the
field means. The convention also locks future archaeology into the
codebase forever — every patch release inherits the previous tags.
**Fix shape**: Sweep in two passes:
1. Strip the leading `v1.4.x [WAVE-CODE] —` marker from any comment whose
   remaining body is still meaningful WHY-narration. Reduces every offender
   without losing intent.
2. Delete the comment outright when the body is just "added the X" or
   "see plan Y". Sample target: `src/proxy.ts:28,32,36` collapse into one
   `// public paths bypassed by auth` block; `src/lib/dashboard-layout.ts:288,294,319,323` lose all four tags and
   the field-doc above each definition stays.
**Effort**: medium (one focused half-day, additive, deletes ~2 000 lines)
`[hotfix-ready]`

### F-2: Seven domain prompt files duplicate the same shell

**Severity**: high
**Category**: duplicate logic
**File(s)**: `src/lib/ai/prompts/bmi.ts:34-61`, `blood-pressure.ts:?`, `weight.ts:46-75`, `pulse.ts:52-81`, `mood.ts`, `general-status.ts`, `medication-compliance.ts`
**What's wrong**: Every file in `src/lib/ai/prompts/` exports the same pair —
`getXSystemPrompt(locale)` returns `${getBaseSystemPrompt(locale)}\n\n${section}`,
and `getXUserPrompt(snapshotJson, todayKey, locale, previousContextBlock?)`
returns a date-prefixed prompt with an optional context block. Only the
DE/EN section constants and the analytical "Analyse the X with focus on…"
sentence differ. The function signature drift risk is real — adding a
new arg today means editing seven files.
**Fix shape**: Replace the seven pairs with a single
`buildDomainPrompts({ id, sectionDe, sectionEn, taskDe, taskEn })` factory
in `prompts/factory.ts` and a registry per metric. The
locale-`en`/-`de` branching in `getXUserPrompt` collapses to one
template-literal interpolation.
**Effort**: small (mechanical, fully covered by existing `__tests__`)

### F-3: `SESSION_SECRET` is documented + required by entrypoint but never read

**Severity**: medium
**Category**: dead code
**File(s)**: `.env.example:48`, `docker-entrypoint.sh:12`, `README.md:94,154`, `CONTRIBUTING.md:25,34`, `docker-compose.yml:23,68`, `docs/self-hosting/scaling.md:24`
**What's wrong**: The env var is listed as required, the docker entrypoint
fails-fast if it is missing, and onboarding docs tell every operator to
generate one with `openssl rand -hex 32`. `grep -rn "SESSION_SECRET" src/`
returns nothing. Sessions are server-stored in `prisma.session` keyed by
the cookie value (`src/lib/auth/session.ts`), so the secret has nothing
to sign. Every self-hoster carries a ceremonial 64-char hex string that
the app ignores. Either (a) wire it into a real signing path (HMAC the
cookie value) or (b) drop the requirement and the docs.
**Fix shape**: Pick (a) or (b). (b) is one removal in
`docker-entrypoint.sh`, the `.env.example` line, two `README.md`
lines, and the `docker-compose.yml` mapping. (a) is a real auth
change and should not be a hotfix.
**Effort**: small (for the deletion path) `[hotfix-ready]` if route (b) chosen

### F-4: 171/535 exported functions in `src/lib/**` have no JSDoc

**Severity**: medium
**Category**: docs gap
**File(s)**: highest offenders by file: `src/lib/dashboard-layout.ts` (0/3 functions documented), `src/lib/telegram.ts` (1/6), `src/lib/process-type.ts` (1/4), `src/lib/glucose.ts` (1/5), `src/lib/utils.ts` (0/1), `src/lib/api-response.ts` (2/4), `src/lib/format-locale.ts` (1/3)
**What's wrong**: The most-imported helpers (`cn()`, `apiError()`,
`safeJson()`, `getProcessType()`, `mgdlToMmol()`, `getGravatarUrl()`)
have no one-line summary. Some have rich type signatures that carry
the meaning; some don't. `safeJson<T>(req, schema)` is a wrapper that
returns an `apiError` `Response` on parse failure — a non-obvious
shape worth documenting once.
**Fix shape**: One-line `/** … */` on every top-10 import. Aim for
WHY/return-shape only, not WHAT. Marc's pattern in
`src/lib/format.ts:40-62` is the model — single-line, locale-aware example
embedded.
**Effort**: medium (manual sweep, ~170 spots) `[hotfix-ready]`

### F-5: `as never` and `as unknown as` chains hide schema drift

**Severity**: medium
**Category**: type safety
**File(s)**: `src/app/api/admin/backups/[id]/restore/route.ts:299,302,357`, `src/lib/personal-records/pr-detection-worker.ts:271,357,434,437,438`, `src/lib/devices/revoke.ts:79`, `src/lib/ai/coach/snapshot.ts:403,482`, `src/lib/ai/prompts/insight-generator.ts:729,730,731,737,738,739` (and 14 more), `src/lib/medications/route-guards.ts:61`, `src/lib/jobs/apple-health-import-worker.ts:85,176,194,195`
**What's wrong**: 20 `as unknown as T` and 9 `as never` assertions. The
PR worker's `where: where as never` and dynamic-key `orderBy` casts
disable the very Prisma narrowing the rest of the file relies on; if
the schema renames a column the worker silently builds a malformed
query at runtime. `MEDICAL_REFERENCE_IDS as unknown as [string, ...string[]]`
in `provider-chain/route.ts:82` exists because Zod wants a non-empty
tuple — a `.refine()` against the readonly array would type-check
without the cast.
**Fix shape**: For each cast, either fix the underlying type or add a
WHY-comment. The Prisma JSON casts in `chart-overlay-prefs`,
`widgets`, `healthkit`, `doctor-report-prefs` (5 sites) collapse onto
one helper `toInputJsonValue<T>(value: T): Prisma.InputJsonValue`. The
`pr-detection-worker.ts` dynamic-orderBy can switch to a
`Record<string, "asc" | "desc">` and drop the cast entirely.
**Effort**: medium

### F-6: Legacy `src/lib/format.ts` is a soft-deprecation that won't die

**Severity**: low
**Category**: simplify | duplicate logic
**File(s)**: `src/lib/format.ts:23-62` (the file itself) and 20 import sites
**What's wrong**: The file's docstring tells new code to use
`useFormatters()` instead, but 20 production import sites still call
`formatDate` / `formatDateTime` / `formatTime` / `formatDateShort`.
The shim reads `document.cookie` on the client and falls back to `en`
on the server, which means SSR can render English where the user has
German selected — exactly the locale hydration mismatch the docstring
warns about.
**Fix shape**: Either migrate the 20 callers to `useFormatters()`
(client) or `makeFormatters(serverLocale)` (server) and delete
`src/lib/format.ts`, or accept it and remove the soft-deprecation
docstring so a future contributor doesn't re-introduce the bug it
warns against.
**Effort**: small (mechanical migration)

### F-7: Mega-files near 1 700 lines in product code

**Severity**: low
**Category**: simplify
**File(s)**: `src/lib/jobs/reminder-worker.ts` (1 653 lines), `src/app/api/insights/targets/route.ts` (1 198), `src/app/api/analytics/route.ts` (1 073), `src/app/api/gamification/achievements/route.ts` (988), `src/components/settings/ai-section.tsx` (1 739), `src/components/charts/health-chart.tsx` (1 710), `src/app/page.tsx` (1 348)
**What's wrong**: Single files holding multiple concerns. `reminder-worker.ts`
mixes scheduling, channel adapters, dedup, and tests-flag logic.
`/api/analytics/route.ts` has an unrelated "slim slice" branch
inlined into the same handler.
**Fix shape**: Only the worker is genuinely a problem — split per
channel and per phase. The route files are acceptable because they
read top-to-bottom; the chart components have to be one file for
Recharts callbacks to share state cheaply. Reminder worker → split
in a dedicated round, not a "while-I'm-here".
**Effort**: large (do not bundle into a hotfix)

### F-8: `coach-prefs` excludeMetrics is a subset enum cast at runtime

**Severity**: low
**Category**: type safety
**File(s)**: `src/lib/ai/coach/snapshot.ts:400-405`
**What's wrong**: `CoachExcludeMetric` is a strict subset of
`CoachScopeSource` and the snapshot loop casts each source via
`as unknown as CoachExcludeMetric` then runs a `Set.has()` lookup as
defence-in-depth. The cast is documented but the comment says
"the runtime check is just defence-in-depth" — which contradicts
the cast. A `(src in EXCLUDABLE_SET)` predicate-typed helper would
remove the cast and keep the narrow type at compile time.
**Fix shape**: Introduce `function isExcludable(src: CoachScopeSource): src is CoachExcludeMetric`.
**Effort**: trivial

### F-9: Prisma JSON serialisation needs one helper

**Severity**: low
**Category**: duplicate logic
**File(s)**: `src/app/api/auth/me/doctor-report-prefs/route.ts:81`, `src/app/api/dashboard/chart-overlay-prefs/route.ts:83`, `src/app/api/dashboard/widgets/route.ts:156`, `src/app/api/integrations/healthkit/route.ts:177`, `src/lib/jobs/apple-health-import-worker.ts:85,176,194,195`
**What's wrong**: Seven sites do `value as unknown as Prisma.InputJsonValue`
to satisfy Prisma's `JsonValue` union. The cast is correct (the values are
plain JSON-serialisable objects) but each call site re-invents the same
escape hatch.
**Fix shape**: One generic helper in `src/lib/db.ts`:
`export const toJson = <T>(v: T) => v as unknown as Prisma.InputJsonValue;`
with a WHY-comment about why the cast is needed.
**Effort**: trivial `[hotfix-ready]`

### F-10: `db-compat.ts` is the maintained migration system

**Severity**: informational
**Category**: dead code (false positive)
**File(s)**: `src/lib/db-compat.ts` (200 lines), 51 call sites
**What's wrong**: At first glance this file looks like accumulated
backwards-compat (which Marc's preferences explicitly forbid). On read
it's the production "ALTER TABLE IF NOT EXISTS" path that bootstraps a
fresh container without `prisma migrate deploy`. Worth a top-of-file
docstring saying so — right now anyone scanning for cruft will flag it.
**Fix shape**: Add a header comment naming it the "schema-bootstrap" path
and pointing at the `prisma/migrations/` directory for the proper
migration history. No code change.
**Effort**: trivial `[hotfix-ready]`

### F-11: `eslint-disable` on `passkey.ts` `response: any` parameters

**Severity**: low
**Category**: type safety
**File(s)**: `src/lib/auth/passkey.ts:103-104,169-170`
**What's wrong**: Both `verifyRegistration` and `verifyAuthentication`
take `response: any` with a per-line eslint-disable. The upstream
`@simplewebauthn/server` exports `RegistrationResponseJSON` and
`AuthenticationResponseJSON` types for these payloads.
**Fix shape**: Import the SimpleWebAuthn types, drop the
`eslint-disable` lines.
**Effort**: trivial

### F-12: Comment quality wins: WHAT-narration leaks

**Severity**: low
**Category**: comment debt
**File(s)**: sample: `src/lib/dashboard-layout.ts:262-263` ("Merge with defaults so new widgets…"), `src/lib/ai/coach/snapshot.ts:413-416` ("Trim down to the metrics…"), `src/app/api/analytics/route.ts:55-66` ("v1.4.33 C1 — slim summaries slice…")
**What's wrong**: Most long block comments narrate WHAT the code does
in plain English right above identical code. Some carry the WHY (the
`/api/analytics` slim-slice block does explain the read-budget
trade-off). The WHAT-only sections should collapse.
**Fix shape**: Treat any block comment whose next 3 lines paraphrase the
comment as deletable. Sample: `dashboard-layout.ts:253-258` keeps the
"v1.4.28 retired" version tag (drop per F-1) and the WHY ("PUT route's
Zod enum rejects the entire blob") — drop the WHAT-rephrasing in the
middle.
**Effort**: medium (folds into F-1 sweep)

### F-13: `route-guards.ts` import is lazy with an unstubbable cast

**Severity**: informational
**Category**: type safety | test discipline
**File(s)**: `src/lib/medications/route-guards.ts:56-62`
**What's wrong**: `loadPrisma()` lazy-imports `@/lib/db` so test files can
stub the module — fine pattern — but the return type forces a
`prisma as unknown as MedicationOwnershipPrisma` cast at the boundary.
`MedicationOwnershipPrisma` is a stripped-down interface declared
locally; the real `PrismaClient` is structurally compatible. The cast
is honest but a brief comment saying "stripped interface for test
stubbability" sits below the function instead of above. Move it up.
**Fix shape**: WHY-comment relocation.
**Effort**: trivial

### F-14: `as never` cast comment in `backups/restore/route.ts` is the right pattern

**Severity**: informational
**Category**: positive example
**File(s)**: `src/app/api/admin/backups/[id]/restore/route.ts:299`
**What's wrong**: Nothing. `type: m.type as never, // already enum-validated above`
is the model for every other cast in F-5: the WHY is the trailing
comment, not a block above. Aim for this in F-5.
**Effort**: n/a

### F-15: Test discipline spot-check is clean

**Severity**: informational
**Category**: test discipline
**File(s)**: 400 test files scanned
**What's wrong**: Nothing material. Every test file contains at least one
`expect()`. No empty `catch` blocks in production tests. No
`try/catch` swallow patterns. The codebase has 0 `TODO`, 0 `FIXME`,
0 `XXX`, 0 `HACK` markers — this is genuinely rare and worth
preserving with a CI grep.
**Fix shape**: Add a tiny CI grep gate enforcing the zero-TODO rule
explicitly, so a future contributor doesn't reintroduce the pattern
in the next marathon.
**Effort**: trivial `[hotfix-ready]`

## Counts

- Files with > 10 obsolete version-tagged comments: **35**
- `any` / `as unknown as` / `as never` cast-throughs: **6 + 20 + 9 = 35** (excluding tests + generated)
- Open TODO / FIXME / XXX / HACK total in product code: **0**
- Exported functions in `src/lib/**` without doc-comment: **171 / 535** (32 %)
- Total `v1.4.x` references in product code: **2 366**
- Test files without `expect()`: **0 / 400**
- `tsc --noEmit` clean: yes
- `pnpm lint` clean: yes

## Out of scope

- Splitting `reminder-worker.ts` (F-7) — wants its own round, not a hotfix.
- Refactoring `health-chart.tsx` (1 710 lines) — Recharts callbacks share
  state cheaply only when colocated; a split needs UX validation first.
- Migration of legacy `src/lib/format.ts` callers (F-6) — touches 20 files
  across the dashboard; defer until the next i18n pass.
- Generated Prisma client (`src/generated/prisma/`) — third-party output,
  not maintained source.
- E2E tests under `e2e/` and `tests/` — separate audit scope.
- Translation/copy quality in `messages/` — separate audit scope.