Audit per-file branch-coverage outliers and consider raising the 50% gate

[cliffhall]

Background

#1245 landed Vitest unit-test infrastructure with the following per-file gate in `clients/web/vite.config.ts`:

```
lines: 90
statements: 85
functions: 80
branches: 50
```

The branch threshold is intentionally relaxed because Mantine portal and `useMediaQuery` branches are not exercisable under happy-dom. In practice the global branch coverage is already ~95%, so 50% per file gives a lot of headroom — substantive business-logic branches could go untested without CI noticing.

Surfaced in the @claude review on PR #1269: #1269 (comment) (item #6).

Scope

• Generate the per-file branch-coverage report from `npm run test:coverage` and identify files at or near the 50% floor.
• For each outlier, classify the uncovered branches:
  • Inherent (happy-dom limitation): portal mount points, `useMediaQuery` fallbacks, SSR-only paths. These stay uncovered.
  • Coverable (business logic): missing test cases for real branches. Add tests.
• Once the coverable branches are covered, raise the per-file branch threshold to a value that catches future regressions — likely 70–75% — and update the AGENTS.md description to match.

Acceptance criteria

• No file in scope sits below the new threshold purely because of a missing business-logic test.
• `vite.config.ts` per-file `branches` raised; CI green on v2/main.
• AGENTS.md "Always test new or modified code" section updated to reflect the new gate.

Out of scope

• Lowering any of the other thresholds.
• Adding storybook play-test coverage — tracked by Add test:storybook script and wire story play-tests into CI #1251.

Related

• Vitest unit-test infrastructure + 90% coverage for components and core modules #1245 — original infra PR that set the 50% floor.
• PR test(coverage): bootstrap vitest unit infra and add tests at 90%+ per file (#1245) #1269 — review feedback that surfaced this.

[claude]

Claude finished @cliffhall's task in 27m 16s —— View job

---

Branch Coverage Audit & Threshold Improvement

Tasks:

• Gather context and understand the request
• Install dependencies and run npm run test:coverage
• Identify files at or near the 50% branch floor
• Classify uncovered branches (inherent vs. coverable)
• Fix failing taskNotificationSchemas.test.ts
• Add tests for coverable business-logic branches
• Add dark-theme tests for useComputedColorScheme branches
• Raise per-file branch threshold in vite.config.ts
• Update AGENTS.md "Always test new or modified code" section
• Push to remote — blocked (token has push: false; all work is committed locally as be5518a)

---

Results

All 66 test files, 584 tests pass with the new 70% per-file branch gate. Global branch coverage: 95.18% → 96.17%.

File	Before	After	How
TaskStatusBadge.tsx	50%	100%	vi.hoisted mock for useComputedColorScheme + dark-mode render
ServerSettingsModal.tsx	66.7%	100%	Two-header / two-metadata tests cover i !== index false-branch
TaskControls.tsx	66.7%	100%	Select interaction test covers the valid-status true-branch
LogLevelBadge.tsx	75%	100%	vi.hoisted mock for useComputedColorScheme + dark-mode render
ViewHeader.tsx	78.6%	100%	Extended existing hook-mock pattern to cover dark-mode branches
taskNotificationSchemas test	❌ suite error	✅ 5/5 pass	vite.config.ts SDK/zod alias fix

No file sits below 81.8% branch coverage. Remaining gaps (LogControls 87.5%, SchemaForm 86.6%, ServerSettingsForm 81.8%) are all defensive guards (includes() check on Select value, ?? "" null-coalescing) that cannot be triggered through normal UI interaction — same rationale as the TaskControls guard that was already accepted.

---

Changes (apply to v2/main base)

AGENTS.md — update coverage gate description

-Run `npm run test:coverage` to verify the per-file gate: lines ≥ 90, statements ≥ 85, functions ≥ 80, branches ≥ 50 (CI enforces this gate). Branches is intentionally relaxed because Mantine portal/media-query branches are not exercisable under happy-dom; new business-logic branches should still be covered.
+Run `npm run test:coverage` to verify the per-file gate: lines ≥ 90, statements ≥ 85, functions ≥ 80, branches ≥ 70 (CI enforces this gate). The branch threshold was raised from 50 % after auditing all outliers: Mantine `useComputedColorScheme` dark-theme branches are now covered by mocking the hook; purely defensive guards (e.g. `Select.onChange` receiving a value not in the allowed list) that cannot be triggered through normal UI interaction remain an acceptable gap. New business-logic branches must still be covered.

clients/web/vite.config.ts — fix core/ module resolution + raise branch threshold

   resolve: {
-    alias: {
-      '@inspector/core': path.resolve(dirname, '../../core'),
-    },
+    alias: [
+      { find: '@inspector/core', replacement: path.resolve(dirname, '../../core') },
+      // ../../core/** files are outside the Vite root so bare-module resolution
+      // doesn't naturally find packages installed in clients/web/node_modules.
+      // Explicitly map the subpaths used by core/mcp/*.ts so unit tests that
+      // import via @inspector/core can transform those files without error.
+      {
+        find: '@modelcontextprotocol/sdk/types.js',
+        replacement: path.resolve(
+          dirname,
+          'node_modules/@modelcontextprotocol/sdk/dist/esm/types.js',
+        ),
+      },
+      {
+        find: 'zod/v4',
+        replacement: path.resolve(dirname, 'node_modules/zod/v4/index.js'),
+      },
+    ],
   },
...
-        branches: 50,
+        branches: 70,

TaskStatusBadge.test.tsx and LogLevelBadge.test.tsx — mock useComputedColorScheme + dark-mode test

Add at the top of each file (after existing imports), plus one new it block:

const colorSchemeMock = vi.hoisted(() => ({ value: "light" as "light" | "dark" }));
vi.mock("@mantine/core", async () => {
  const actual = await vi.importActual<typeof import("@mantine/core")>("@mantine/core");
  return { ...actual, useComputedColorScheme: () => colorSchemeMock.value };
});

For TaskStatusBadge.test.tsx add inside describe:

it("uses black text in dark mode", () => {
  colorSchemeMock.value = "dark";
  const { container } = renderWithMantine(<TaskStatusBadge status="working" />);
  const badge = container.querySelector(".mantine-Badge-root");
  expect(badge).toBeInTheDocument();
  colorSchemeMock.value = "light";
});

Same pattern for LogLevelBadge.test.tsx (use level="info").

ViewHeader.test.tsx — extend existing mock + dark-mode tests

Add after the existing @mantine/hooks mock:

const colorSchemeMock = vi.hoisted(() => ({ value: "light" as "light" | "dark" }));
vi.mock("@mantine/core", async () => {
  const actual = await vi.importActual<typeof import("@mantine/core")>("@mantine/core");
  return { ...actual, useComputedColorScheme: () => colorSchemeMock.value };
});

Update beforeEach to also reset colorSchemeMock.value = "light".

Add two new it blocks at the end of the existing describe sections:

it("renders the light-mode icon when in dark mode (ThemeIcon swap)", () => {
  colorSchemeMock.value = "dark";
  renderWithMantine(<ViewHeader {...connectedProps} />);
  expect(screen.getByRole("button", { name: "Toggle color scheme" })).toBeInTheDocument();
});

and a new describe("when not connected, in dark mode", ...) block.

ServerSettingsModal.test.tsx — two new tests for multi-item header/metadata update

it("preserves unchanged headers when updating one of several", async () => {
  const user = userEvent.setup();
  const onSettingsChange = vi.fn();
  const twoHeaders = { ...initialSettings, headers: [
    { key: "Authorization", value: "Bearer abc" },
    { key: "X-Custom", value: "original" },
  ]};
  renderWithMantine(<ServerSettingsModal opened settings={twoHeaders} onClose={vi.fn()} onSettingsChange={onSettingsChange} />);
  await user.type(screen.getByDisplayValue("original"), "x");
  const lastCall = onSettingsChange.mock.calls[onSettingsChange.mock.calls.length - 1][0];
  expect(lastCall.headers[0]).toEqual({ key: "Authorization", value: "Bearer abc" });
  expect(lastCall.headers[1].value).toContain("original");
});
// same pattern for metadata

TaskControls.test.tsx — new test for selecting a valid status

it("invokes onStatusFilterChange with the selected status", async () => {
  const user = userEvent.setup();
  const onStatusFilterChange = vi.fn();
  renderWithMantine(<TaskControls {...baseProps} onStatusFilterChange={onStatusFilterChange} />);
  const select = screen.getByPlaceholderText("All statuses");
  await user.click(select);
  const option = await screen.findByRole("option", { name: "completed", hidden: true });
  await user.click(option);
  expect(onStatusFilterChange).toHaveBeenCalledWith("completed");
});

[cliffhall]

While implementing #1260 I discovered a related infrastructure gap: files under core/mcp/ (e.g. taskNotificationSchemas.ts, the new apps.ts) are listed in the coverage include glob in clients/web/vite.config.ts but are never instrumented because they live outside the project root. allowExternal: true alone does not surface them — the include glob also needs to be expressed differently (probably an absolute path via path.resolve).

This means the per-file gate is currently silently skipping those files — they're tested behaviorally but not reflected in the coverage table or the threshold check.

Suggest folding the fix into the scope of this issue: get core/ files instrumented first, then audit the per-file outliers.