shirokuma-docs 0.1.0-alpha.1

package/plugin/shirokuma-skills-ja/skills/reviewing-on-issue/docs/workflows/annotation-consistency.md

@@ -0,0 +1,256 @@
+# Annotation Consistency Verification Workflow
+
+## Overview
+
+JSDocアノテーションと実際のコードの整合性を検証するワークフロー。
+手動確認が必要だった `@usedComponents`, `@usedActions`, `@dbTables` 等の検証を自動化。
+
+---
+
+## Verification Types
+
+| Annotation | Source of Truth | Verification Method |
+|------------|-----------------|---------------------|
+| `@usedComponents` | import文 | Grep + AST解析 |
+| `@usedActions` | import文 + 関数呼び出し | Grep + AST解析 |
+| `@usedInScreen` | 親ファイルのimport | 逆方向検索 |
+| `@usedInComponent` | 呼び出し元ファイル | 逆方向検索 |
+| `@dbTables` | Drizzle ORM参照 | Grep (from句, join句) |
+| `@route` | ファイルパス | ディレクトリ構造 |
+
+---
+
+## Workflow Steps
+
+### Step 1: Extract Annotations
+
+対象ファイルからJSDocを抽出し、アノテーション値をパース。
+
+```typescript
+// Example: nav-tags.tsx
+/**
+ * @usedComponents SidebarGroup, SidebarMenu, Badge
+ */
+// Parsed: ["SidebarGroup", "SidebarMenu", "Badge"]
+```
+
+### Step 2: Extract Actual Usage
+
+実際のimport文・関数呼び出しを解析。
+
+```typescript
+// Actual imports in nav-tags.tsx
+import { Badge } from "@/components/ui/badge"
+import {
+  SidebarGroup,
+  SidebarGroupLabel,  // <- Missing in annotation!
+  SidebarMenu,
+  SidebarMenuButton,  // <- Missing in annotation!
+  SidebarMenuItem,    // <- Missing in annotation!
+} from "@/components/ui/sidebar"
+// Parsed: ["Badge", "SidebarGroup", "SidebarGroupLabel", "SidebarMenu", "SidebarMenuButton", "SidebarMenuItem"]
+```
+
+### Step 3: Compare and Report
+
+不一致を検出してレポート生成。
+
+| Type | Description | Example |
+|------|-------------|---------|
+| `missing` | アノテーションにない | `SidebarGroupLabel` (imported but not in @usedComponents) |
+| `extra` | 実際には使用されていない | `Foo` (in @usedComponents but not imported) |
+| `typo` | スペルミスの可能性 | `SideBarGroup` vs `SidebarGroup` |
+
+---
+
+## Verification Commands
+
+### Manual (using Grep)
+
+```bash
+# 1. Get annotation value
+grep -A1 "@usedComponents" apps/public/components/nav-tags.tsx
+
+# 2. Get actual imports (component pattern)
+grep -E "^import.*from" apps/public/components/nav-tags.tsx | \
+  grep -oE '\b[A-Z][a-zA-Z]+\b' | sort -u
+
+# 3. Compare manually
+```
+
+### Automated (future shirokuma-docs command)
+
+```bash
+# Proposed command
+shirokuma-docs lint-annotations -p . -c shirokuma-docs.config.yaml
+
+# Output format
+Annotation consistency check:
+  nav-tags.tsx:
+    @usedComponents:
+      - MISSING: SidebarGroupLabel, SidebarMenuButton, SidebarMenuItem
+      + annotation: SidebarGroup, SidebarMenu, Badge
+      ✓ imports: Badge, SidebarGroup, SidebarGroupLabel, SidebarMenu, SidebarMenuButton, SidebarMenuItem
+```
+
+---
+
+## Review Checklist
+
+### @usedComponents
+
+- [ ] All imported UI components are listed
+- [ ] No extra components that aren't imported
+- [ ] Order matches import order (optional)
+- [ ] Includes shadcn/ui components
+- [ ] Includes custom components
+
+### @usedActions
+
+- [ ] All imported Server Actions are listed
+- [ ] Functions are actually called in component
+- [ ] Includes dynamic imports (if any)
+
+### @usedInScreen / @usedInComponent
+
+- [ ] Component is actually imported in listed screens/components
+- [ ] No stale references to removed screens
+- [ ] Bidirectional consistency (A uses B ↔ B usedIn A)
+
+### @dbTables
+
+- [ ] All tables in FROM clause listed
+- [ ] All tables in JOIN clause listed
+- [ ] Subquery tables included
+- [ ] relation() targets included
+
+---
+
+## Fix Patterns
+
+### Pattern 1: Update Annotation to Match Imports
+
+```typescript
+// Before
+/**
+ * @usedComponents SidebarGroup, SidebarMenu
+ */
+
+// After (add all imported components)
+/**
+ * @usedComponents SidebarGroup, SidebarGroupLabel, SidebarMenu, SidebarMenuButton, SidebarMenuItem, Badge
+ */
+```
+
+### Pattern 2: Remove Unused Import
+
+```typescript
+// Before
+import { Unused } from "@/components/ui/unused"
+/**
+ * @usedComponents Used, Unused
+ */
+
+// After (remove from both)
+// No import
+/**
+ * @usedComponents Used
+ */
+```
+
+### Pattern 3: Add Missing Import
+
+```typescript
+// Before
+/**
+ * @usedComponents A, B, C  // C is listed but not imported
+ */
+
+// After (either add import or remove from annotation)
+import { C } from "@/components/c"
+/**
+ * @usedComponents A, B, C
+ */
+```
+
+---
+
+## Integration with Reviewer Agent
+
+### Trigger Keywords
+
+- "annotation review", "アノテーションレビュー"
+- "check usedComponents", "usedComponents確認"
+- "verify annotations", "アノテーション検証"
+
+### Role Assignment
+
+Add to **code** role as sub-check:
+
+```markdown
+### Annotation Consistency (Sub-check)
+- Load: workflows/annotation-consistency.md
+- Check: @usedComponents, @usedActions, @dbTables
+- Report: Mismatches and fixes
+```
+
+---
+
+## Scope Definitions
+
+### Components to Check
+
+| Path Pattern | Annotation | Source of Truth |
+|--------------|------------|-----------------|
+| `components/*.tsx` | `@usedComponents` | Import statements |
+| `app/**/page.tsx` | `@usedActions` | Import + function calls |
+| `lib/actions/*.ts` | `@dbTables` | Drizzle query references |
+
+### Exclusions
+
+- `components/ui/**` (shadcn/ui - no custom annotations)
+- `__tests__/**` (test files)
+- `*.d.ts` (type definitions)
+
+---
+
+## Future: CLI Integration
+
+### Proposed shirokuma-docs lint-annotations
+
+```yaml
+# shirokuma-docs.config.yaml
+lintAnnotations:
+  enabled: true
+  rules:
+    usedComponents-match:
+      severity: warning
+      checkOrder: false
+    usedActions-match:
+      severity: warning
+    dbTables-match:
+      severity: error
+  exclude:
+    - "components/ui/**"
+```
+
+### Output Formats
+
+```bash
+# Terminal (human-readable)
+shirokuma-docs lint-annotations -f terminal
+
+# JSON (machine-readable)
+shirokuma-docs lint-annotations -f json -o /tmp/annotations.json
+
+# Fix mode (auto-update annotations)
+shirokuma-docs lint-annotations --fix
+```
+
+---
+
+## Related Files
+
+- [shirokuma-docs-annotations.md](../patterns/shirokuma-docs-annotations.md) - Annotation reference
+- [shirokuma-docs-verification.md](./shirokuma-docs-verification.md) - General verification workflow
+- [code.md](../roles/code.md) - Code review role

package/plugin/shirokuma-skills-ja/skills/reviewing-on-issue/docs/workflows/shirokuma-docs-verification.md

@@ -0,0 +1,219 @@
+# shirokuma-docs Verification Workflow
+
+## Overview
+
+shirokuma-docs を使用したコード品質検証のワークフロー。
+レビュー時に機械的にチェック可能な項目を自動検証する。
+
+---
+
+## Verification Flow
+
+```
+1. Run Checks → 2. Analyze Issues → 3. Fix Issues → 4. Re-verify → 5. Report
+```
+
+---
+
+## Step 1: Run All Checks
+
+```bash
+# Navigate to project root
+cd /path/to/project
+
+# 1. Test documentation check
+shirokuma-docs lint-tests -p . -c shirokuma-docs.config.yaml -f terminal
+
+# 2. Implementation-test coverage
+shirokuma-docs lint-coverage -p . -c shirokuma-docs.config.yaml
+
+# 3. Documentation structure (if OVERVIEW.md/ADR exists)
+shirokuma-docs lint-docs -p . -c shirokuma-docs.config.yaml
+
+# 4. Code structure check (Server Actions) - NEW
+shirokuma-docs lint-code -p . -c shirokuma-docs.config.yaml -f terminal
+```
+
+**Expected Output**:
+- `lint-tests`: Missing/duplicate @testdoc warnings
+- `lint-coverage`: Uncovered source files list
+- `lint-docs`: Missing sections/files warnings
+- `lint-code`: Server Action structure issues, missing annotations
+
+---
+
+## Step 2: Analyze Issues
+
+### lint-tests Issues
+
+| Issue | Cause | Fix |
+|-------|-------|-----|
+| `Missing @testdoc` | Test has no JSDoc | Add @testdoc comment |
+| `Duplicate @testdoc` | Same description used | Make descriptions unique |
+| `Missing Japanese` | @testdoc not in Japanese | Write in Japanese |
+
+### lint-coverage Issues
+
+| Issue | Cause | Fix |
+|-------|-------|-----|
+| `No test file` | Source has no test | Create test file OR add `@skip-test` |
+| `Orphan test` | Test has no source | Remove or link to source |
+
+### lint-docs Issues
+
+| Issue | Cause | Fix |
+|-------|-------|-----|
+| `Missing file` | Required doc not found | Create the document |
+| `Missing section` | Section not in doc | Add the section |
+| `Invalid frontmatter` | YAML error | Fix frontmatter syntax |
+
+### lint-code Issues (NEW)
+
+| Issue | Cause | Fix |
+|-------|-------|-----|
+| `server-action-structure` | Auth/CSRF/Zod order wrong | Reorder: auth → CSRF → Zod |
+| `annotation-required` | Missing @screen/@serverAction | Add required annotation |
+| `Missing @serverAction` | "use server" file has no JSDoc | Add @serverAction comment |
+| `Missing @screen` | page.tsx has no JSDoc | Add @screen comment |
+
+---
+
+## Step 3: Fix Issues
+
+### Adding @testdoc Comments
+
+```typescript
+// Before
+it("should create user", async () => { ... });
+
+// After
+/**
+ * @testdoc 有効なデータで新規ユーザーを作成できる
+ * @purpose ユーザー作成の正常系確認
+ * @expected ユーザーが作成され、IDが返される
+ */
+it("should create user", async () => { ... });
+```
+
+### Adding @skip-test for Non-testable Files
+
+```typescript
+/**
+ * UI Component Types
+ * @skip-test shadcn/ui 型定義のみ
+ */
+export interface ButtonProps { ... }
+```
+
+### Adding Server Action Annotations
+
+```typescript
+// Before
+export async function getProjects() { ... }
+
+// After
+/**
+ * プロジェクト一覧取得
+ * @serverAction
+ * @feature ProjectManagement
+ * @dbTables projects, project_members
+ */
+export async function getProjects() { ... }
+```
+
+---
+
+## Step 4: Re-verify
+
+```bash
+# Run checks again after fixes
+shirokuma-docs lint-tests -p . -c shirokuma-docs.config.yaml -f summary
+shirokuma-docs lint-coverage -p . -c shirokuma-docs.config.yaml -f summary
+
+# Strict mode for CI (exits with error code if issues remain)
+shirokuma-docs lint-tests -p . --strict
+shirokuma-docs lint-coverage -p . --strict -s
+```
+
+**Pass Criteria**:
+- `lint-tests`: No errors (warnings acceptable)
+- `lint-coverage`: All source files have tests OR @skip-test
+- `lint-docs`: All required sections present
+
+---
+
+## Step 5: Report
+
+Include in review report:
+
+```markdown
+## shirokuma-docs Verification
+
+### lint-tests
+- Total tests: 150
+- With @testdoc: 148 (98.7%)
+- Issues: 2 warnings (duplicate descriptions)
+
+### lint-coverage
+- Source files: 45
+- Covered: 42 (93.3%)
+- Skipped: 3 (with @skip-test)
+
+### lint-docs
+- OVERVIEW.md: ✅ All sections present
+- ADR count: 5/3 required ✅
+```
+
+---
+
+## Quick Reference
+
+### Essential Commands
+
+```bash
+# Quick check (summary only)
+shirokuma-docs lint-tests -p . -f summary
+shirokuma-docs lint-coverage -p . -f summary
+
+# Detailed report
+shirokuma-docs lint-tests -p . -f terminal
+shirokuma-docs lint-coverage -p .
+
+# CI mode (fail on error)
+shirokuma-docs lint-tests -p . --strict
+shirokuma-docs lint-coverage -p . -s
+
+# Generate documentation
+shirokuma-docs generate -p .
+```
+
+### Configuration
+
+```yaml
+# shirokuma-docs.config.yaml
+lintTests:
+  rules:
+    testdoc-required: { severity: "warning" }
+    testdoc-japanese: { severity: "warning" }
+    duplicate-testdoc: { severity: "error" }
+
+lintCoverage:
+  enabled: true
+  conventions:
+    - source: "apps/web/lib/actions/*.ts"
+      test: "apps/web/__tests__/lib/actions/*.test.ts"
+  exclude:
+    - "apps/web/components/ui/**"
+    - "**/types.ts"
+```
+
+---
+
+## Integration with Review Roles
+
+This workflow integrates with:
+- **Testing Role**: `shirokuma-docs lint-tests` + `lint-coverage`
+- **Code Role**: `shirokuma-docs lint-code` (Server Action structure)
+- **Next.js Role**: All linters + `feature-map` generation
+
+See [../AGENT.md](../AGENT.md) for role-specific instructions.

package/plugin/shirokuma-skills-ja/skills/reviewing-on-issue/patterns/account-lockout.md

@@ -0,0 +1,177 @@
+# アカウントロックアウトパターン
+
+## 概要
+
+Redis ベースのアカウントロックアウトシステム。ブルートフォース攻撃を防止。指数バックオフとプライバシー保護のためのメールハッシュを使用。
+
+## 実装パターン
+
+### コアコンポーネント
+
+```typescript
+// packages/database/src/rate-limit.ts
+import { createHash } from "crypto";
+
+export async function checkAccountLockout(
+  redis: Redis,
+  email: string
+): Promise<{ locked: boolean; remainingTime?: number }> {
+  const emailHash = hashEmail(email);
+  const key = `account_lockout:${emailHash}`;
+
+  const attempts = await redis.get(key);
+  if (!attempts) return { locked: false };
+
+  const count = parseInt(attempts, 10);
+  const ttl = await redis.ttl(key);
+
+  // 15分以内に5回の試行でロックアウト
+  if (count >= 5) {
+    return { locked: true, remainingTime: ttl };
+  }
+
+  return { locked: false };
+}
+
+export async function recordFailedAttempt(
+  redis: Redis,
+  email: string
+): Promise<void> {
+  const emailHash = hashEmail(email);
+  const key = `account_lockout:${emailHash}`;
+
+  const current = await redis.incr(key);
+
+  if (current === 1) {
+    // 初回試行: 15分ウィンドウ
+    await redis.expire(key, 15 * 60);
+  } else if (current >= 5) {
+    // ロックアウト: 1時間に延長
+    await redis.expire(key, 60 * 60);
+  }
+}
+
+function hashEmail(email: string): string {
+  return createHash("sha256")
+    .update(email.toLowerCase().trim())
+    .digest("hex");
+}
+```
+
+## しきい値
+
+| レベル | 試行回数 | ウィンドウ | アクション |
+|--------|----------|-----------|-----------|
+| 警告 | 1-4 | 15分 | 試行を追跡 |
+| ロックアウト | 5回以上 | 1時間 | 認証をブロック |
+| 拡張 | 10回以上 | 24時間 | 長期ブロック（将来） |
+
+## プライバシー考慮事項
+
+1. **メールハッシュ**: Redis でのメール露出を防ぐため SHA-256 を使用
+2. **キーに PII なし**: Redis キーにはハッシュのみ
+3. **一定タイミング**: ユーザーが存在しなくても常にロックアウトをチェック
+4. **ユーザーへのフィードバックなし**: メールの存在を明かさない
+
+## Fail-Closed 動作
+
+```typescript
+// Redis が利用不可の場合、fail-closed（認証を拒否）
+export async function checkAccountLockout(
+  redis: Redis,
+  email: string
+): Promise<{ locked: boolean; remainingTime?: number }> {
+  try {
+    // ... 通常のロジック
+  } catch (error) {
+    console.error("Redis error during lockout check:", error);
+    // Fail closed: Redis ダウン時はロック済みとして扱う
+    return { locked: true, remainingTime: 900 };
+  }
+}
+```
+
+## 認証との統合
+
+```typescript
+// apps/admin/lib/actions/auth.ts
+export async function signInAction(credentials: SignInInput) {
+  const startTime = Date.now();
+
+  // 1. DB クエリの前にロックアウトをチェック
+  const lockout = await checkAccountLockout(redis, credentials.email);
+  if (lockout.locked) {
+    await waitForMinimumDuration(startTime, 500);
+    return { error: "Too many failed attempts" };
+  }
+
+  // 2. 認証
+  const result = await auth.api.signInEmail({ body: credentials });
+
+  if (!result) {
+    // 3. 失敗を記録
+    await recordFailedAttempt(redis, credentials.email);
+    await waitForMinimumDuration(startTime, 500);
+    return { error: "Invalid credentials" };
+  }
+
+  // 4. 成功時にロックアウトをクリア
+  await clearAccountLockout(redis, credentials.email);
+
+  return { success: true };
+}
+```
+
+## レビューチェックリスト
+
+- [ ] Redis 格納前にメールがハッシュ化されている
+- [ ] DB クエリの前にロックアウトをチェック
+- [ ] Redis エラー時の fail-closed 動作
+- [ ] タイミング攻撃の防止（一定時間）
+- [ ] TTL が正しく設定（15分 → 1時間エスカレーション）
+- [ ] ログイン成功時にロックアウトをクリア
+- [ ] エラーメッセージによるユーザー列挙なし
+
+## よくある問題
+
+1. **ロックアウトが解除されない**: 成功時に `clearAccountLockout()` が呼ばれているか確認
+2. **ユーザー列挙**: ロック時/無効時に同じエラーメッセージを使用
+3. **Redis メモリ**: LRU エビクションポリシーを実装
+4. **分散システム**: マルチインスタンスデプロイでは集中型 Redis を検討
+
+## テスト
+
+```typescript
+// tests/e2e/account-lockout.spec.ts
+test("locks account after 5 failed attempts", async ({ page }) => {
+  for (let i = 0; i < 5; i++) {
+    await signIn(page, "test@example.com", "wrongpassword");
+  }
+
+  // 6回目はブロックされるべき
+  const response = await signIn(page, "test@example.com", "correctpassword");
+  expect(response.error).toContain("Too many failed attempts");
+});
+
+test("lockout expires after 1 hour", async ({ page }) => {
+  // ロックアウトをトリガー
+  for (let i = 0; i < 5; i++) {
+    await signIn(page, "test@example.com", "wrongpassword");
+  }
+
+  // Redis 時間を早送り（テスト環境）
+  await redis.expire(`account_lockout:${hash}`, 1);
+  await new Promise(resolve => setTimeout(resolve, 1100));
+
+  // 成功するはず
+  const response = await signIn(page, "test@example.com", "correctpassword");
+  expect(response.success).toBe(true);
+});
+```
+
+## 監視すべきメトリクス
+
+- ロックアウト発生率（攻撃のアラート）
+- 誤検知率（正規ユーザーのロック）
+- Redis レイテンシ/可用性
+- ロックアウト解除までの平均時間