test(coverage): cover stat-items and read-content fs-error branches

Mock node:fs and resolvePath so the filesystem-error mapping branches
become deterministically reachable:

- stat-items: ENOENT -> 'Path not found', EACCES/EPERM -> permission
  denied, uncoded Error and non-Error rejections -> generic 'Failed to
  get stats', and an McpError passed straight through.
- read-content: EISDIR/EACCES/EPERM specific messages plus the basic
  'Filesystem error' fallbacks (unknown code, non-object rejection), the
  ENOENT resolved-path message, and the whole-file (no-range) read path.

These are the real error-mapping branches the integration suites can't
hit with a live filesystem.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: shtse8

__tests__/handlers/read-content.errors.test.ts

@@ -0,0 +1,86 @@
+import { vi, describe, it, expect, beforeEach } from 'vitest';
+
+// Mock fs.stat/readFile and resolvePath so the specific filesystem-error
+// messages in getSpecificFsErrorMessage (EISDIR / EACCES / EPERM) and the
+// basic-message fallbacks are reachable without relying on real OS errors.
+vi.mock('node:fs', () => ({
+  promises: {
+    stat: vi.fn().mockName('fs.stat'),
+    readFile: vi.fn().mockName('fs.readFile'),
+  },
+}));
+
+vi.mock('../../src/utils/path-utils.js', () => ({
+  resolvePath: vi.fn().mockName('pathUtils.resolvePath'),
+  PROJECT_ROOT: '/project-root',
+}));
+
+const isFileStat = (isFile: boolean) => ({ isFile: () => isFile });
+
+describe('read-content filesystem-error branches', () => {
+  let handler: (args: unknown) => Promise<{ content: { text: string }[] }>;
+  let fsMock: { stat: ReturnType<typeof vi.fn>; readFile: ReturnType<typeof vi.fn> };
+  let resolvePath: ReturnType<typeof vi.fn>;
+
+  beforeEach(async () => {
+    fsMock = (await import('node:fs')).promises as never;
+    resolvePath = (await import('../../src/utils/path-utils.js')).resolvePath as never;
+    vi.resetAllMocks();
+    resolvePath.mockImplementation((p: string) => `/project-root/${p}`);
+    fsMock.stat.mockResolvedValue(isFileStat(true));
+    const { readContentToolDefinition } = await import('../../src/handlers/read-content.js');
+    handler = readContentToolDefinition.handler;
+  });
+
+  const firstError = async (args: unknown) => {
+    const res = await handler(args);
+    return JSON.parse(res.content[0].text)[0].error as string;
+  };
+
+  it('maps EISDIR to a "Path is a directory" message with the relative path', async () => {
+    fsMock.stat.mockRejectedValue(Object.assign(new Error('x'), { code: 'EISDIR' }));
+    expect(await firstError({ paths: ['somedir'] })).toBe(
+      'Path is a directory, not a file: somedir',
+    );
+  });
+
+  it('maps EACCES to a permission-denied read message', async () => {
+    fsMock.stat.mockRejectedValue(Object.assign(new Error('x'), { code: 'EACCES' }));
+    expect(await firstError({ paths: ['locked.txt'] })).toBe(
+      'Permission denied reading file: locked.txt',
+    );
+  });
+
+  it('maps EPERM to a permission-denied read message', async () => {
+    fsMock.stat.mockRejectedValue(Object.assign(new Error('x'), { code: 'EPERM' }));
+    expect(await firstError({ paths: ['locked.txt'] })).toMatch(/Permission denied reading file/);
+  });
+
+  it('falls back to a basic filesystem-error message for an unknown code', async () => {
+    fsMock.stat.mockRejectedValue(Object.assign(new Error('weird'), { code: 'EBUSY' }));
+    expect(await firstError({ paths: ['busy.txt'] })).toBe('Filesystem error: weird');
+  });
+
+  it('falls back to a basic message for a non-object rejection', async () => {
+    fsMock.stat.mockRejectedValue('totally not an error object');
+    expect(await firstError({ paths: ['weird.txt'] })).toBe(
+      'Filesystem error: totally not an error object',
+    );
+  });
+
+  it('returns ENOENT "File not found" with the resolved target path', async () => {
+    fsMock.stat.mockRejectedValue(Object.assign(new Error('x'), { code: 'ENOENT' }));
+    const err = await firstError({ paths: ['gone.txt'] });
+    expect(err).toMatch(/File not found at resolved path '\/project-root\/gone.txt'/);
+    expect(err).toContain("from relative path 'gone.txt'");
+  });
+
+  it('reads the whole file when no line range is given', async () => {
+    fsMock.stat.mockResolvedValue(isFileStat(true));
+    fsMock.readFile.mockResolvedValue('full body');
+    const res = await handler({ paths: ['whole.txt'] });
+    const parsed = JSON.parse(res.content[0].text)[0];
+    expect(parsed.content).toBe('full body');
+    expect(parsed.error).toBeUndefined();
+  });
+});

__tests__/handlers/stat-items.errors.test.ts

@@ -0,0 +1,78 @@
+import { vi, describe, it, expect, beforeEach } from 'vitest';
+
+// Mock fs.stat and resolvePath so the error-mapping branches in handleStatError
+// (ENOENT / EACCES / EPERM / generic) and the rejected-settled branch are all
+// reachable deterministically.
+vi.mock('node:fs', () => ({
+  promises: {
+    stat: vi.fn().mockName('fs.stat'),
+  },
+}));
+
+vi.mock('../../src/utils/path-utils', () => ({
+  resolvePath: vi.fn().mockName('pathUtils.resolvePath'),
+  PROJECT_ROOT: '/project-root',
+}));
+
+describe('stat-items error branches', () => {
+  let handler: (args: unknown) => Promise<{ content: { text: string }[] }>;
+  let fsMock: { stat: ReturnType<typeof vi.fn> };
+  let resolvePath: ReturnType<typeof vi.fn>;
+
+  beforeEach(async () => {
+    fsMock = (await import('node:fs')).promises as never;
+    resolvePath = (await import('../../src/utils/path-utils')).resolvePath as never;
+    vi.resetAllMocks();
+    resolvePath.mockImplementation((p: string) => `/project-root/${p}`);
+    const { statItemsToolDefinition } = await import('../../src/handlers/stat-items');
+    handler = statItemsToolDefinition.handler;
+  });
+
+  const firstResult = async (args: unknown) => {
+    const res = await handler(args);
+    return JSON.parse(res.content[0].text)[0];
+  };
+
+  it('maps ENOENT to a "Path not found" error', async () => {
+    fsMock.stat.mockRejectedValue(Object.assign(new Error('nope'), { code: 'ENOENT' }));
+    const r = await firstResult({ paths: ['missing.txt'] });
+    expect(r.status).toBe('error');
+    expect(r.error).toBe('Path not found');
+  });
+
+  it('maps EACCES to a permission-denied error including the path', async () => {
+    fsMock.stat.mockRejectedValue(Object.assign(new Error('x'), { code: 'EACCES' }));
+    const r = await firstResult({ paths: ['locked.txt'] });
+    expect(r.error).toBe('Permission denied stating path: locked.txt');
+  });
+
+  it('maps EPERM to a permission-denied error', async () => {
+    fsMock.stat.mockRejectedValue(Object.assign(new Error('x'), { code: 'EPERM' }));
+    const r = await firstResult({ paths: ['locked.txt'] });
+    expect(r.error).toMatch(/Permission denied stating path/);
+  });
+
+  it('falls back to a generic "Failed to get stats" message for an uncoded error', async () => {
+    fsMock.stat.mockRejectedValue(new Error('disk on fire'));
+    const r = await firstResult({ paths: ['weird.txt'] });
+    expect(r.error).toBe('Failed to get stats: disk on fire');
+  });
+
+  it('passes an McpError message straight through (resolvePath rejection)', async () => {
+    const { McpError, ErrorCode } = await import('@modelcontextprotocol/sdk/types.js');
+    resolvePath.mockRejectedValueOnce(new McpError(ErrorCode.InvalidParams, 'bad path'));
+    const r = await firstResult({ paths: ['../escape'] });
+    expect(r.error).toBe('bad path');
+  });
+
+  it('stringifies a non-Error rejection in the generic branch', async () => {
+    fsMock.stat.mockRejectedValue('plain string failure');
+    const r = await firstResult({ paths: ['weird.txt'] });
+    expect(r.error).toBe('Failed to get stats: plain string failure');
+  });
+
+  it('rejects an empty paths array via the Zod schema', async () => {
+    const { McpError } = await import('@modelcontextprotocol/sdk/types.js');
+    await expect(handler({ paths: [] })).rejects.toBeInstanceOf(McpError);
+  });
+});