shirokuma-docs 0.1.0-alpha.1

package/plugin/shirokuma-skills-ja/skills/reviewing-on-issue/criteria/code-quality.md

@@ -0,0 +1,303 @@
+# コード品質レビュー基準
+
+## TypeScript
+
+### 必須プラクティス
+
+- [ ] `any` ではなく `unknown` を使用
+- [ ] 公開 API に明示的な戻り値型を付与
+- [ ] ランタイム型チェックに型ガードを使用
+- [ ] tsconfig.json で strict モード有効化
+- [ ] 根拠なしの型アサーション (`as`) 禁止
+
+### 例
+
+```typescript
+// Bad
+function parse(data: any): any {
+  return data.items
+}
+
+// Good
+function parse(data: unknown): Item[] {
+  if (!isValidData(data)) {
+    throw new Error("Invalid data format")
+  }
+  return data.items
+}
+
+function isValidData(data: unknown): data is { items: Item[] } {
+  return typeof data === "object" && data !== null && "items" in data
+}
+```
+
+## エラーハンドリング
+
+### 必須プラクティス
+
+- [ ] 空の catch ブロック禁止
+- [ ] エラーメッセージにコンテキストを含める
+- [ ] エラー種別ごとにカスタムエラークラスを使用
+- [ ] 適切なレベルでエラーをログ出力
+- [ ] 内部エラー詳細をユーザーに公開しない
+
+### 例
+
+```typescript
+// Bad
+try {
+  await saveData()
+} catch {
+  // empty
+}
+
+// Good
+try {
+  await saveData()
+} catch (error) {
+  console.error("Failed to save data:", { error, userId, action: "save" })
+  return { success: false, error: "Operation failed" }
+}
+```
+
+## 非同期パターン
+
+### 必須プラクティス
+
+- [ ] 並列操作には `Promise.all()` を使用
+- [ ] 部分的失敗を許容する場合は `Promise.allSettled()` を使用
+- [ ] async/await と `.then()` チェーンを混在させない
+- [ ] Promise の reject を適切にハンドリング
+
+### 例
+
+```typescript
+// Bad: 並列可能なのに逐次実行
+const user = await getUser(id)
+const posts = await getPosts(id)
+const comments = await getComments(id)
+
+// Good: 並列取得
+const [user, posts, comments] = await Promise.all([
+  getUser(id),
+  getPosts(id),
+  getComments(id),
+])
+```
+
+## コードスタイル
+
+### 必須プラクティス
+
+- [ ] 関数は小さく、単一責任に集中
+- [ ] ネスト最大3レベル
+- [ ] 説明的な変数名（省略形を避ける）
+- [ ] 命名規則の統一: 変数は camelCase、コンポーネントは PascalCase
+
+### 命名ガイドライン
+
+| 種類 | 規則 | 例 |
+|------|------|-----|
+| 変数 | camelCase | `userName`, `postCount` |
+| 関数 | camelCase | `getUserById`, `createPost` |
+| コンポーネント | PascalCase | `UserProfile`, `PostList` |
+| 定数 | UPPER_SNAKE | `MAX_RETRIES`, `API_URL` |
+| 型/インターフェース | PascalCase | `UserData`, `PostInput` |
+
+## コードスメル
+
+### 修正必須
+
+1. **God Object**: 責務過多のクラス/モジュール
+2. **マジックナンバー**: 説明のないハードコード値
+3. **デッドコード**: 未使用の関数、import、変数
+4. **重複コード**: 複数箇所の同一ロジック
+5. **長いパラメータリスト**: 3-4個を超えるパラメータ
+6. **Feature Envy**: 他クラスのデータに過度に依存するメソッド
+
+### 修正例
+
+```typescript
+// Bad: マジックナンバー
+if (password.length < 8) { ... }
+
+// Good: 名前付き定数
+const MIN_PASSWORD_LENGTH = 8
+if (password.length < MIN_PASSWORD_LENGTH) { ... }
+
+// Bad: 長いパラメータリスト
+function createUser(name, email, password, role, department, manager, startDate) { ... }
+
+// Good: オブジェクトパラメータ
+function createUser(params: CreateUserParams) { ... }
+```
+
+## 関数設計
+
+### ガイドライン
+
+- **単一責任**: 1関数1目的
+- **純粋関数**: 副作用のない関数を優先
+- **早期リターン**: 無効ケースは早めに返す
+- **最大パラメータ数**: 関数は3個、それ以上はオブジェクトを使用
+
+### 例
+
+```typescript
+// Bad: 複数の責務
+function processUser(user: User) {
+  // Validate
+  if (!user.email) throw new Error("No email")
+  // Transform
+  user.name = user.name.trim()
+  // Save
+  await db.insert(users).values(user)
+  // Notify
+  await sendEmail(user.email, "Welcome!")
+}
+
+// Good: 単一責任
+function validateUser(user: User): void { ... }
+function normalizeUser(user: User): User { ... }
+function saveUser(user: User): Promise<User> { ... }
+function notifyUser(user: User): Promise<void> { ... }
+
+async function createUser(input: CreateUserInput): Promise<User> {
+  validateUser(input)
+  const normalized = normalizeUser(input)
+  const user = await saveUser(normalized)
+  await notifyUser(user)
+  return user
+}
+```
+
+## import の整理
+
+### 順序
+
+1. 外部パッケージ (react, next, etc.)
+2. 内部パッケージ (@repo/database)
+3. ローカル絶対パス (@/lib, @/components)
+4. 相対パス (./utils, ../types)
+
+### 例
+
+```typescript
+// External
+import { useState } from "react"
+import { z } from "zod"
+
+// Internal packages
+import { db, posts } from "@repo/database"
+
+// Local absolute
+import { auth } from "@/lib/auth"
+import { Button } from "@/components/ui/button"
+
+// Relative
+import { formatDate } from "./utils"
+import type { PostFormProps } from "./types"
+```
+
+## コメント
+
+### 使うべき場面
+
+- 複雑なビジネスロジック
+- 非自明なワークアラウンド
+- Issue 参照付き TODO
+- 公開 API のドキュメント
+
+### 使わないべき場面
+
+- 自明なコード
+- コメントアウトされたコード
+- 冗長な説明
+
+```typescript
+// Bad: 自明なコメント
+// Loop through users
+for (const user of users) { ... }
+
+// Good: WHY を説明
+// Skip inactive users to avoid sending emails to abandoned accounts
+const activeUsers = users.filter(u => u.lastLoginAt > thirtyDaysAgo)
+```
+
+## ドキュメント品質
+
+### 必須プラクティス
+
+- [ ] 公開関数に JSDoc コメントあり
+- [ ] すべてのパラメータを `@param` で記載
+- [ ] 戻り値を `@returns` で記載
+- [ ] 複雑な関数は `@example` 付き
+- [ ] 関連関数を `@see` でリンク
+- [ ] エラー条件を `@throws` で記載
+- [ ] TypeDoc 用に `@category` で関数をグループ化
+- [ ] 内部関数は `@internal` でマーク
+- [ ] 型/インターフェースにプロパティレベルのドキュメントあり
+
+### JSDoc 完全性
+
+| 関数タイプ | 必須タグ |
+|-----------|---------|
+| 公開 Server Action | `@param`, `@returns`, `@example`, `@category` |
+| 公開 Getter | `@returns`, `@example`, `@category` |
+| 内部ヘルパー | `@internal` |
+| 型/インターフェース | `@example`, `@category`, プロパティコメント |
+
+### 例: 十分にドキュメント化された関数
+
+```typescript
+/**
+ * ページネーション付きで投稿を取得
+ *
+ * 管理画面の投稿一覧ページで使用。指定したページの投稿と
+ * ページネーション情報を返します。
+ *
+ * @param page - ページ番号（1から開始、デフォルト: 1）
+ * @param pageSize - 1ページあたりの表示件数（デフォルト: 10）
+ * @returns ページネーション結果
+ *
+ * @example
+ * ```typescript
+ * const result = await getPaginatedPosts(1, 10)
+ * console.log(`${result.total}件中 ${result.items.length}件を表示`)
+ * ```
+ *
+ * @see {@link getPosts} - 全件取得する場合
+ *
+ * @category 投稿取得
+ */
+export async function getPaginatedPosts(
+  page: number = 1,
+  pageSize: number = 10
+): Promise<PaginatedResult<Post>> {
+  // implementation
+}
+```
+
+### 例: 不十分なドキュメント
+
+```typescript
+// BAD: 必須タグがすべて欠落
+/**
+ * Get posts
+ */
+export async function getPosts() {
+  // implementation
+}
+```
+
+### レビュー基準
+
+1. **完全性**: すべての公開 API に JSDoc あり
+2. **正確性**: ドキュメントが実際の動作と一致
+3. **例**: 現実的で動作するコード例
+4. **相互参照**: 関連関数が @see でリンク
+5. **カテゴリ**: 一貫した TypeDoc カテゴリ分類
+
+### 関連ファイル
+
+- `patterns/jsdoc.md` - 完全な JSDoc パターンとタグリファレンス

package/plugin/shirokuma-skills-ja/skills/reviewing-on-issue/criteria/coding-conventions.md

@@ -0,0 +1,419 @@
+# コーディング規約レビュー基準
+
+## 概要
+
+Next.js 16 + React 19 + TypeScript プロジェクトのコーディング規約。
+コードレビュー時の一貫性・保守性チェックに使用。
+
+## ファイル命名
+
+### 必須規約
+
+| 種類 | 規則 | 例 |
+|------|------|-----|
+| コンポーネント | kebab-case | `post-form.tsx`, `user-nav.tsx` |
+| ページ | kebab-case | `page.tsx`, `layout.tsx` |
+| ユーティリティ | kebab-case | `auth-client.ts`, `utils.ts` |
+| Server Actions | kebab-case | `posts.ts`, `categories.ts` |
+| テストファイル | kebab-case + `.test` or `.spec` | `posts.test.ts`, `auth.spec.ts` |
+| Hooks | `use-` prefix + kebab-case | `use-mobile.tsx`, `use-auth.ts` |
+
+### レビューチェックリスト
+
+- [ ] コンポーネントファイルは kebab-case（PascalCase ではない）
+- [ ] Hook ファイルは `use-` で始まる
+- [ ] テストファイルは `.test.ts` または `.spec.ts` で終わる
+- [ ] ファイル名にスペースや特殊文字なし
+
+---
+
+## 変数・関数の命名
+
+### 必須規約
+
+| 種類 | 規則 | 例 |
+|------|------|-----|
+| 変数 | camelCase | `userName`, `postCount`, `isLoading` |
+| 関数 | camelCase (動詞 + 名詞) | `getUserById`, `createPost` |
+| コンポーネント | PascalCase | `UserProfile`, `PostForm` |
+| 定数 | UPPER_SNAKE_CASE | `MAX_RETRIES`, `API_BASE_URL` |
+| 型/インターフェース | PascalCase | `UserData`, `PostInput` |
+| Boolean | `is`/`has`/`can`/`should` prefix | `isLoading`, `hasPermission` |
+
+### レビューチェックリスト
+
+- [ ] 変数は camelCase
+- [ ] 関数は camelCase + 動詞 prefix (get, create, update, delete, handle)
+- [ ] React コンポーネントは PascalCase
+- [ ] 定数は UPPER_SNAKE_CASE
+- [ ] Boolean 変数に適切な prefix あり
+
+### 例
+
+```typescript
+// Good
+const userName = "John"
+const isLoading = false
+const MAX_RETRIES = 3
+function getUserById(id: string) { }
+function PostForm({ post }: PostFormProps) { }
+
+// Bad
+const user_name = "John"     // snake_case
+const loading = false        // boolean prefix なし
+const maxRetries = 3         // 定数は UPPER_SNAKE
+function GetUserById() { }   // 関数に PascalCase
+function postForm() { }      // コンポーネントに camelCase
+```
+
+---
+
+## import の整理
+
+### 必須順序
+
+グループ間に空行を入れて以下の順序で整理:
+
+1. **React/Next.js** (フレームワーク)
+2. **外部パッケージ** (npm)
+3. **内部パッケージ** (モノレポ @repo/*)
+4. **ローカル絶対パス** (@/ エイリアス)
+5. **相対パス** (./)
+
+### レビューチェックリスト
+
+- [ ] import がカテゴリ別にグループ化
+- [ ] グループ間に空行あり
+- [ ] 型 import は `import type` を使用
+- [ ] 未使用の import なし
+
+### 例
+
+```typescript
+// 1. Framework
+import { useState, useTransition } from "react"
+import { useRouter } from "next/navigation"
+import Link from "next/link"
+
+// 2. External packages
+import { z } from "zod"
+import { useTranslations } from "next-intl"
+
+// 3. Internal packages
+import { db, posts, eq } from "@repo/database"
+
+// 4. Local absolute
+import { auth } from "@/lib/auth"
+import { Button } from "@/components/ui/button"
+
+// 5. Relative
+import { formatDate } from "./utils"
+import type { PostFormProps } from "./types"
+```
+
+---
+
+## TypeScript 規約
+
+### 必須プラクティス
+
+- [ ] `any` 型禁止（`unknown` を使用）
+- [ ] エクスポート関数に明示的な戻り値型
+- [ ] ランタイム型チェックに型ガード使用
+- [ ] 未使用変数は `_` prefix
+- [ ] オブジェクト型は `interface`、ユニオン/エイリアスは `type`
+
+### 例
+
+```typescript
+// Good: unknown instead of any
+function parse(data: unknown): Item[] {
+  if (!isValidData(data)) throw new Error("Invalid")
+  return data.items
+}
+
+// Good: Type guard
+function isValidData(data: unknown): data is { items: Item[] } {
+  return typeof data === "object" && data !== null && "items" in data
+}
+
+// Good: Explicit return type
+export async function getPosts(): Promise<Post[]> { }
+
+// Good: Unused variable prefix
+function handler(_req: Request, res: Response) { }
+
+// Bad
+function parse(data: any): any { }  // any type
+export async function getPosts() { }  // missing return type
+function handler(req: Request) { }    // unused without prefix
+```
+
+---
+
+## コンポーネント構造
+
+### 必須順序
+
+1. ディレクティブ (`"use client"` or `"use server"`)
+2. import (上記グループ順)
+3. 型定義 (小規模な場合)
+4. コンポーネント関数
+   - Hooks を最初に
+   - 派生値
+   - イベントハンドラ
+   - JSX を return
+
+### レビューチェックリスト
+
+- [ ] ディレクティブが先頭行（必要な場合）
+- [ ] import がグループ化ルールに従う
+- [ ] Hooks がコンポーネント本体の先頭
+- [ ] イベントハンドラが return 前に定義
+- [ ] コンポーネントがエクスポート済み
+
+### 例
+
+```typescript
+"use client"
+
+import { useState } from "react"
+import { useTranslations } from "next-intl"
+import { Button } from "@/components/ui/button"
+
+interface Props {
+  title: string
+}
+
+export function MyComponent({ title }: Props) {
+  // 1. Hooks
+  const [value, setValue] = useState("")
+  const t = useTranslations("namespace")
+
+  // 2. Derived values
+  const isValid = value.length > 0
+
+  // 3. Handlers
+  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    setValue(e.target.value)
+  }
+
+  // 4. Render
+  return (
+    <div>
+      <h1>{title}</h1>
+      <input value={value} onChange={handleChange} />
+      <Button disabled={!isValid}>{t("submit")}</Button>
+    </div>
+  )
+}
+```
+
+---
+
+## Server Action 構造
+
+### 必須順序
+
+1. `"use server"` ディレクティブ
+2. import
+3. バリデーションスキーマ（内部）
+4. 戻り値型定義
+5. JSDoc 付きエクスポート関数
+
+### 必須パターン
+
+- [ ] 認証チェックが最初
+- [ ] Zod による入力バリデーション
+- [ ] DB 操作に try/catch
+- [ ] 一貫した戻り値型 (`ActionResult<T>`)
+- [ ] ミューテーション後に `revalidatePath`
+- [ ] 公開関数に JSDoc
+
+### 例
+
+```typescript
+"use server"
+
+import { revalidatePath } from "next/cache"
+import { headers } from "next/headers"
+import { db, posts } from "@repo/database"
+import { z } from "zod"
+
+const Schema = z.object({
+  title: z.string().min(1).max(200),
+})
+
+type ActionResult<T = void> =
+  | { success: true; data?: T }
+  | { success: false; error: string }
+
+/**
+ * Create a new post
+ * @param formData - Form data containing post fields
+ * @returns ActionResult with post ID on success
+ */
+export async function createPost(formData: FormData): Promise<ActionResult<{ id: string }>> {
+  // 1. Auth
+  const session = await verifyAdmin(await headers())
+  if (!session) return { success: false, error: "Unauthorized" }
+
+  // 2. Validate
+  const validated = Schema.safeParse({ title: formData.get("title") })
+  if (!validated.success) {
+    return { success: false, error: validated.error.errors[0].message }
+  }
+
+  // 3. Database with try/catch
+  try {
+    const [result] = await db.insert(posts).values(validated.data).returning()
+    revalidatePath("/posts")
+    return { success: true, data: { id: result.id } }
+  } catch (error) {
+    console.error("Failed:", error)
+    return { success: false, error: "Operation failed" }
+  }
+}
+```
+
+---
+
+## コードスタイル
+
+### ネスト上限
+
+- [ ] ネスト最大3レベル
+- [ ] 早期リターンでネストを削減
+
+```typescript
+// Bad: 4+ levels
+if (a) {
+  if (b) {
+    if (c) {
+      if (d) { }  // Too deep
+    }
+  }
+}
+
+// Good: Early returns
+if (!a) return
+if (!b) return
+if (!c) return
+// Process d
+```
+
+### 関数の長さ
+
+- [ ] 関数は50行未満
+- [ ] 単一責任の原則
+- [ ] 複雑なロジックはヘルパー関数に抽出
+
+### パラメータ数
+
+- [ ] 最大3パラメータ
+- [ ] それ以上はオブジェクトパラメータを使用
+
+```typescript
+// Bad
+function create(name, email, role, dept, manager) { }
+
+// Good
+function create(params: CreateParams) { }
+```
+
+### マジックナンバー
+
+- [ ] コンテキストなしのハードコード数値禁止
+- [ ] 名前付き定数を使用
+
+```typescript
+// Bad
+if (password.length < 8) { }
+
+// Good
+const MIN_PASSWORD_LENGTH = 8
+if (password.length < MIN_PASSWORD_LENGTH) { }
+```
+
+---
+
+## ESLint + Prettier + Stylistic 設定
+
+### 有効ルール
+
+| ルール | レベル | 説明 |
+|--------|--------|------|
+| `@typescript-eslint/no-explicit-any` | warn | `any` 型の使用を抑制 |
+| `@typescript-eslint/no-unused-vars` | warn | 未使用変数は `_` prefix 必須 |
+| `react-hooks/rules-of-hooks` | error | Hooks ルールを強制 |
+| `react-hooks/exhaustive-deps` | warn | 依存配列チェック |
+| `@stylistic/object-curly-newline` | error | 型定義は必ず複数行 |
+| `no-console` | warn | console.log禁止 (warn/error除く) |
+
+### 型定義フォーマット（必須）
+
+型リテラル・interfaceは必ず複数行にする:
+
+```typescript
+// Bad - 1行
+topActions: { action: string; count: number }[]
+
+// Good - 複数行
+topActions: {
+  action: string
+  count: number
+}[]
+```
+
+ESLint Stylistic ルール:
+```javascript
+"@stylistic/object-curly-newline": ["error", {
+  TSTypeLiteral: "always",
+  TSInterfaceBody: "always",
+}]
+```
+
+### フォーマットコマンド
+
+```bash
+pnpm --filter {app} lint        # ESLintチェック
+pnpm --filter {app} lint:fix    # ESLint自動修正
+pnpm --filter {app} format      # Prettier整形
+pnpm --filter {app} fix         # 一括修正（推奨）
+```
+
+### ESLint チェック
+
+- [ ] `any` 型なし（または根拠付きコメントあり）
+- [ ] すべての変数が使用されているか `_` prefix あり
+- [ ] React hooks が rules of hooks に準拠
+- [ ] **型定義が複数行になっているか**
+- [ ] Next.js Image/Link コンポーネントが正しく使用されているか
+
+---
+
+## サマリーチェックリスト
+
+### クイックレビュー
+
+- [ ] ファイル命名が kebab-case 規約に準拠
+- [ ] 変数/関数が正しいケーシングを使用
+- [ ] import が整理・グループ化済み
+- [ ] TypeScript 型が明示的（`any` なし）
+- [ ] コンポーネントが構造パターンに準拠
+- [ ] Server Actions に認証・バリデーション・エラーハンドリングあり
+- [ ] 深いネストなし（最大3レベル）
+- [ ] マジックナンバーなし
+- [ ] 関数が集中的で短い
+
+### よくある問題
+
+| 問題 | 修正 |
+|------|------|
+| PascalCase ファイル名 | kebab-case にリネーム |
+| `any` 型 | `unknown` + 型ガードに置換 |
+| 整理されていない import | グループ化して空行追加 |
+| 戻り値型の欠落 | 明示的な `Promise<T>` を追加 |
+| 深いネスト | 早期リターンを使用 |
+| マジックナンバー | 定数に抽出 |
+| 長い関数 | 小さな関数に分割 |