shirokuma-docs 0.1.0-alpha.1

package/plugin/shirokuma-skills-en/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-en/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-en/skills/reviewing-on-issue/patterns/account-lockout.md

@@ -0,0 +1,177 @@
+# Account Lockout Pattern
+
+## Overview
+
+Redis-based account lockout system to prevent brute force attacks. Uses exponential backoff with privacy-preserving email hashing.
+
+## Implementation Pattern
+
+### Core Components
+
+```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);
+
+  // 5 attempts in 15 minutes → lockout
+  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) {
+    // First attempt: 15 minute window
+    await redis.expire(key, 15 * 60);
+  } else if (current >= 5) {
+    // Lockout: extend to 1 hour
+    await redis.expire(key, 60 * 60);
+  }
+}
+
+function hashEmail(email: string): string {
+  return createHash("sha256")
+    .update(email.toLowerCase().trim())
+    .digest("hex");
+}
+```
+
+## Thresholds
+
+| Level | Attempts | Window | Action |
+|-------|----------|--------|--------|
+| Warning | 1-4 | 15 minutes | Track attempts |
+| Lockout | 5+ | 1 hour | Block authentication |
+| Extended | 10+ | 24 hours | Long-term block (future) |
+
+## Privacy Considerations
+
+1. **Email Hashing**: Use SHA-256 to prevent email exposure in Redis
+2. **No PII in Keys**: Redis keys contain only hashes
+3. **Consistent Timing**: Always check lockout even if user doesn't exist
+4. **No User Feedback**: Don't reveal if email exists
+
+## Fail-Closed Behavior
+
+```typescript
+// If Redis is unavailable, fail closed (reject auth)
+export async function checkAccountLockout(
+  redis: Redis,
+  email: string
+): Promise<{ locked: boolean; remainingTime?: number }> {
+  try {
+    // ... normal logic
+  } catch (error) {
+    console.error("Redis error during lockout check:", error);
+    // Fail closed: treat as locked when Redis is down
+    return { locked: true, remainingTime: 900 };
+  }
+}
+```
+
+## Integration with Auth
+
+```typescript
+// apps/admin/lib/actions/auth.ts
+export async function signInAction(credentials: SignInInput) {
+  const startTime = Date.now();
+
+  // 1. Check lockout BEFORE any DB queries
+  const lockout = await checkAccountLockout(redis, credentials.email);
+  if (lockout.locked) {
+    await waitForMinimumDuration(startTime, 500);
+    return { error: "Too many failed attempts" };
+  }
+
+  // 2. Authenticate
+  const result = await auth.api.signInEmail({ body: credentials });
+
+  if (!result) {
+    // 3. Record failure
+    await recordFailedAttempt(redis, credentials.email);
+    await waitForMinimumDuration(startTime, 500);
+    return { error: "Invalid credentials" };
+  }
+
+  // 4. Clear lockout on success
+  await clearAccountLockout(redis, credentials.email);
+
+  return { success: true };
+}
+```
+
+## Review Checklist
+
+- [ ] Email is hashed before Redis storage
+- [ ] Lockout checked BEFORE database queries
+- [ ] Fail-closed behavior on Redis errors
+- [ ] Timing attacks prevented (consistent duration)
+- [ ] TTL set correctly (15min → 1hr escalation)
+- [ ] Successful login clears lockout
+- [ ] No user enumeration via error messages
+
+## Common Issues
+
+1. **Lockout not clearing**: Ensure `clearAccountLockout()` called on success
+2. **User enumeration**: Use same error message for locked/invalid
+3. **Redis memory**: Implement LRU eviction policy
+4. **Distributed systems**: Consider centralized Redis for multi-instance deployments
+
+## Testing
+
+```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");
+  }
+
+  // 6th attempt should be blocked
+  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 }) => {
+  // Trigger lockout
+  for (let i = 0; i < 5; i++) {
+    await signIn(page, "test@example.com", "wrongpassword");
+  }
+
+  // Fast-forward Redis time (in test environment)
+  await redis.expire(`account_lockout:${hash}`, 1);
+  await new Promise(resolve => setTimeout(resolve, 1100));
+
+  // Should succeed now
+  const response = await signIn(page, "test@example.com", "correctpassword");
+  expect(response.success).toBe(true);
+});
+```
+
+## Metrics to Monitor
+
+- Lockout trigger rate (alerts for attacks)
+- False positive rate (legitimate users locked)
+- Redis latency/availability
+- Average time to lockout clear