feat: add msw-auto-mock for OpenAPI-based mock generation (#2668)

* feat: add msw-auto-mock for OpenAPI-based mock generation

OpenAPI spec から MSW ハンドラーを自動生成する msw-auto-mock を導入し、
Storybook の Story と API テストを追加。

- msw-auto-mock + @faker-js/faker を devDependencies に追加
- generate-mock スクリプト追加（ja ロケール自動適用）
- PostList の Storybook Story（Default / ServerError / NetworkError / Empty）
- apiClient と post.queries のユニットテスト（MSW server.use パターン）
- oxlint / oxfmt の ignore に src/mocks/** を追加
- テスト・Story 向けの unsafe 系ルール緩和

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

* docs: update rules for msw-auto-mock integration

- commands.md: generate-mock コマンド追加
- mocks.md: msw-auto-mock の運用ルール、ファイル構成表
- storybook.md: MSW Story パターン、inline: false の説明
- api.md: src/mocks/ の手動編集禁止ルール
- testing.md: server.use() パターンの具体例

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

* docs: rewrite rules in English and simplify

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

* fix: lint

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: devmgn

.claude/rules/api.md

@@ -6,6 +6,7 @@ paths:
 # API Layer Rules
 
 - **Never manually edit** files in `src/api/openapi/` — regenerate with `pnpm generate-api`
+- **Never manually edit** files in `src/mocks/` (except `server.ts`) — regenerate with `pnpm generate-mock`
 
 ## TanStack Query Pattern
 

.claude/rules/commands.md

@@ -21,5 +21,6 @@ pnpm storybook                      # Storybook dev server
 pnpm build-storybook                # Storybook static build
 pnpm generate-api                   # Generate OpenAPI client
 pnpm generate-api:clean             # Clean + regenerate OpenAPI client
+pnpm generate-mock                  # Generate MSW handlers from OpenAPI spec
 pnpm analyze                        # Bundle size analysis (requires build)
 ```

.claude/rules/mocks.md

@@ -6,6 +6,19 @@ paths:
 # MSW Mock Rules
 
 - Worker directory: `./public`
-- Vitest: `setupServer()` — shared instance in `src/mocks/server.ts`
+- Vitest: shared `setupServer()` in `src/mocks/server.ts`
 - Storybook: `mswLoader` in `.storybook/preview.tsx` (NOT `setupWorker()`)
 - Test isolation: `server.resetHandlers()` runs in `afterEach` automatically
+
+## msw-auto-mock
+
+- `pnpm generate-mock` generates `src/mocks/handlers.ts` from `openapi.yml`
+- Auto-patches to `@faker-js/faker/locale/ja` (Japanese data, deterministic via `faker.seed(1)`)
+- **Never manually edit** generated files — re-run `pnpm generate-mock` after spec changes
+
+## Files
+
+| File                                                | Purpose                                                     | Managed   |
+| --------------------------------------------------- | ----------------------------------------------------------- | --------- |
+| `handlers.ts`, `browser.ts`, `node.ts`, `native.ts` | Auto-generated from OpenAPI                                 | Generated |
+| `server.ts`                                         | Vitest shared instance (empty, use `server.use()` per test) | Manual    |

.claude/rules/storybook.md

@@ -32,6 +32,33 @@ type Story = StoryObj<typeof ComponentName>;
 export const Default: Story = {};
 ```
 
+## MSW Story Pattern
+
+Use `parameters.msw.handlers` with auto-generated or custom handlers. Set `inline: false` when stories for the same endpoint return different responses (required for Docs page MSW isolation).
+
+```typescript
+const meta = {
+  component: PostList,
+  parameters: {
+    docs: { story: { inline: false } },
+    msw: { handlers },
+  },
+} satisfies Meta<typeof PostList>;
+
+export const ServerError: Story = {
+  parameters: {
+    docs: { story: { inline: false } },
+    msw: {
+      handlers: [
+        http.get("https://...", () =>
+          HttpResponse.json({ message: "Error" }, { status: 500 }),
+        ),
+      ],
+    },
+  },
+};
+```
+
 ## MCP Integration
 
 Use `storybook-mcp` tools: `list-all-documentation`, `get-documentation`, `get-documentation-for-story`, `get-storybook-story-instructions`, `preview-stories`, `run-story-tests`.

.claude/rules/testing.md

@@ -21,4 +21,15 @@ paths:
 
 ## API Mocking
 
-Import shared MSW server: `import { server } from "../../mocks/server"` then `server.use(http.get(...))`.
+Use shared MSW server with per-test handlers. `resetHandlers()` runs automatically in `afterEach`.
+
+```typescript
+import { HttpResponse, http } from "msw";
+import { server } from "../../mocks/server";
+
+server.use(
+  http.get(`${BASE_URL}/posts`, () => HttpResponse.json([...])),
+);
+```
+
+- Cast `request.json()` as `Record<string, unknown>` when spreading into response

oxfmt.config.ts

@@ -1,7 +1,12 @@
 import { defineConfig } from "oxfmt";
 
 export default defineConfig({
-  ignorePatterns: [".*/skills/**", "public/**", "src/api/openapi/**"],
+  ignorePatterns: [
+    ".*/skills/**",
+    "public/**",
+    "src/api/openapi/**",
+    "src/mocks/**",
+  ],
   printWidth: 80,
   experimentalSortImports: {
     groups: [

oxlint.config.ts

@@ -42,6 +42,7 @@ export default defineConfig({
     "out/**",
     "public/**",
     "src/api/openapi/**",
+    "src/mocks/**",
     "storybook-static/**",
   ],
   categories: {
@@ -185,6 +186,8 @@ export default defineConfig({
         "react/rules-of-hooks": "off",
         "typescript/consistent-type-assertions": "off",
         "typescript/no-explicit-any": "off",
+        "typescript/no-unsafe-argument": "off",
+        "typescript/no-unsafe-assignment": "off",
 
         // eslint-plugin-storybook (jsPlugin)
         "storybook/await-interactions": "error",
@@ -222,6 +225,7 @@ export default defineConfig({
         "eslint/no-undef": "off",
         "typescript/consistent-type-assertions": "off",
         "typescript/no-explicit-any": "off",
+        "typescript/no-unsafe-argument": "off",
         "typescript/no-unsafe-assignment": "off",
         "typescript/no-unsafe-type-assertion": "off",
         "vitest/consistent-test-it": ["error", { fn: "it" }],

package.json

@@ -23,7 +23,8 @@
     "storybook": "storybook dev -p 6006",
     "build-storybook": "storybook build",
     "generate-api": "pnpm dlx @openapitools/openapi-generator-cli generate -i openapi.yml -g typescript-fetch -o ./src/api/openapi -c openapiconfig.json --openapi-normalizer SET_TAGS_FOR_ALL_OPERATIONS=default",
-    "generate-api:clean": "rm -rf src/api/openapi && pnpm generate-api"
+    "generate-api:clean": "rm -rf src/api/openapi && pnpm generate-api",
+    "generate-mock": "msw-auto-mock openapi.yml -o ./src/mocks --typescript --base-url https://jsonplaceholder.typicode.com && sed -i '' 's|from \"@faker-js/faker\"|from \"@faker-js/faker/locale/ja\"|' ./src/mocks/handlers.ts"
   },
   "dependencies": {
     "@hookform/resolvers": "5.2.2",
@@ -45,6 +46,7 @@
     "zod": "4.3.6"
   },
   "devDependencies": {
+    "@faker-js/faker": "10.4.0",
     "@next/env": "16.2.1",
     "@storybook/addon-a11y": "10.3.3",
     "@storybook/addon-docs": "10.3.3",
@@ -71,6 +73,7 @@
     "jest-extended": "7.0.0",
     "knip": "6.1.0",
     "msw": "2.12.14",
+    "msw-auto-mock": "0.32.0",
     "msw-storybook-addon": "2.0.6",
     "oxfmt": "0.42.0",
     "oxlint": "1.57.0",