shirokuma-docs 0.1.0-alpha.1

package/plugin/shirokuma-skills-en/skills/codebase-rule-discovery/patterns/discovery-categories.md

@@ -0,0 +1,191 @@
+# Discovery Categories
+
+Categories of patterns to discover across TypeScript applications.
+
+## 1. Structural Patterns
+
+### File Naming
+
+| Pattern | Grep Command | Rule Potential |
+|---------|--------------|----------------|
+| kebab-case files | `find . -name "*.ts" \| grep -E "[a-z]+-[a-z]+"` | naming-convention |
+| PascalCase components | `find . -name "*.tsx" \| grep -E "^[A-Z]"` | component-naming |
+| index.ts re-exports | `find . -name "index.ts"` | barrel-exports |
+
+### Export Patterns
+
+```bash
+# Default vs named exports
+grep -r "^export default" --include="*.ts" | wc -l
+grep -r "^export function" --include="*.ts" | wc -l
+grep -r "^export const" --include="*.ts" | wc -l
+```
+
+### Import Ordering
+
+```bash
+# Check import groups (react, next, lib, local)
+grep -A10 "^import" --include="*.tsx" | head -50
+```
+
+## 2. Code Quality Patterns
+
+### Error Handling
+
+```bash
+# try-catch usage
+grep -rn "try {" --include="*.ts"
+
+# Error logging
+grep -rn "console.error" --include="*.ts"
+grep -rn "logger.error" --include="*.ts"
+
+# Error types
+grep -rn "throw new Error" --include="*.ts"
+grep -rn "throw new [A-Z].*Error" --include="*.ts"
+```
+
+### Async Patterns
+
+```bash
+# Async function declarations
+grep -rn "async function" --include="*.ts"
+
+# Promise handling
+grep -rn "\.then(" --include="*.ts"
+grep -rn "await " --include="*.ts"
+
+# Promise.all usage
+grep -rn "Promise.all" --include="*.ts"
+```
+
+### Type Safety
+
+```bash
+# any usage
+grep -rn ": any" --include="*.ts"
+grep -rn "as any" --include="*.ts"
+
+# unknown usage
+grep -rn ": unknown" --include="*.ts"
+
+# Type assertions
+grep -rn "as [A-Z]" --include="*.ts"
+```
+
+## 3. Framework Patterns
+
+### Server Actions
+
+```bash
+# "use server" declarations
+grep -rn '"use server"' --include="*.ts"
+
+# Auth patterns
+grep -rn "verifyAuth\|verifyAuthMutation" --include="*.ts"
+
+# CSRF patterns
+grep -rn "validateCSRF\|csrfProtect" --include="*.ts"
+
+# Zod validation
+grep -rn "\.parse(\|\.safeParse(" --include="*.ts"
+```
+
+### React Components
+
+```bash
+# Function components
+grep -rn "^export function [A-Z]" --include="*.tsx"
+
+# Props interfaces
+grep -rn "interface.*Props" --include="*.tsx"
+
+# Use of hooks
+grep -rn "use[A-Z][a-zA-Z]*(" --include="*.tsx"
+```
+
+### i18n Patterns
+
+```bash
+# useTranslations usage
+grep -rn "useTranslations" --include="*.tsx"
+
+# t() calls
+grep -rn "t\(['\"]" --include="*.tsx"
+
+# Translation key format
+grep -rn 't("' --include="*.tsx" | sed 's/.*t("//' | sed 's/".*//' | sort | uniq
+```
+
+## 4. Documentation Patterns
+
+### JSDoc Coverage
+
+```bash
+# JSDoc blocks
+grep -rn "/\*\*" --include="*.ts"
+
+# @description tags
+grep -rn "@description" --include="*.ts"
+
+# @param tags
+grep -rn "@param" --include="*.ts"
+
+# @returns tags
+grep -rn "@returns\|@return" --include="*.ts"
+```
+
+### Custom Annotations
+
+```bash
+# shirokuma-docs annotations
+grep -rn "@screen\|@component\|@serverAction" --include="*.ts"
+grep -rn "@usedComponents\|@usedActions" --include="*.ts"
+grep -rn "@dbTables\|@feature" --include="*.ts"
+```
+
+### TODO/FIXME Tracking
+
+```bash
+# TODO comments
+grep -rn "// TODO\|// FIXME" --include="*.ts"
+
+# With assignee
+grep -rn "// TODO(@" --include="*.ts"
+```
+
+## 5. Testing Patterns
+
+### Test Structure
+
+```bash
+# describe blocks
+grep -rn "describe(" --include="*.test.ts"
+
+# it/test blocks
+grep -rn "it(\|test(" --include="*.test.ts"
+
+# @testdoc annotations
+grep -rn "@testdoc" --include="*.test.ts"
+```
+
+### Mock Patterns
+
+```bash
+# jest.mock usage
+grep -rn "jest.mock" --include="*.test.ts"
+
+# vi.mock (Vitest)
+grep -rn "vi.mock" --include="*.test.ts"
+```
+
+## Analysis Matrix
+
+| Category | Admin | Public | Web | MCP | shirokuma |
+|----------|-------|--------|-----|-----|-----------|
+| Error handling | ? | ? | ? | ? | ? |
+| Type safety | ? | ? | ? | ? | ? |
+| JSDoc coverage | ? | ? | ? | ? | ? |
+| Server Actions | ? | ? | ? | N/A | N/A |
+
+Fill in counts during analysis to identify patterns and inconsistencies.

package/plugin/shirokuma-skills-en/skills/codebase-rule-discovery/templates/convention-proposal.md

@@ -0,0 +1,138 @@
+# Convention Proposal Template
+
+規約を提案し、それによって可能になるチェックを明確にするテンプレート。
+
+---
+
+# Convention Proposal: {convention-name}
+
+**Date**: YYYY-MM-DD
+**Category**: {File Placement | Naming | Code Structure | Annotation | i18n}
+**Priority**: {P0 | P1 | P2}
+
+## 現状分析
+
+### 現在の状態
+
+{現在どのように書かれているか}
+
+| App | パターンA | パターンB | その他 |
+|-----|----------|----------|--------|
+| blog-cms (admin) | X件 | Y件 | Z件 |
+| blog-cms (public) | X件 | Y件 | Z件 |
+
+### 問題点
+
+1. {問題1: 不統一による問題}
+2. {問題2: 機械的チェックができない}
+3. {問題3: 新規参画者の混乱}
+
+## 提案規約
+
+### 規約内容
+
+```
+{具体的なルール}
+例: Server Actionファイルは `lib/actions/{domain}.ts` に配置する
+```
+
+### 詳細仕様
+
+| 項目 | 規約 | 例 |
+|------|------|-----|
+| {項目1} | {規約} | {例} |
+| {項目2} | {規約} | {例} |
+
+### 許容パターン
+
+```typescript
+// ✅ OK
+{許容されるコード例}
+
+// ❌ NG
+{許容されないコード例}
+```
+
+## チェック可能性
+
+### この規約で可能になるチェック
+
+| チェック | 説明 | severity |
+|---------|------|----------|
+| {check-1} | {説明} | error/warning/info |
+| {check-2} | {説明} | error/warning/info |
+
+### 実装イメージ
+
+```typescript
+// shirokuma-docs lint rule
+export const {ruleName}Rule: LintRule = {
+  id: "{rule-id}",
+  check(file, allFiles) {
+    // {チェックロジック概要}
+  }
+}
+```
+
+## 移行計画
+
+### 影響範囲
+
+| App | 変更必要ファイル数 | 工数見積 |
+|-----|------------------|---------|
+| blog-cms | X件 | Y時間 |
+
+### 移行手順
+
+1. {手順1}
+2. {手順2}
+3. {手順3}
+
+### 自動修正可能性
+
+- [ ] 完全自動修正可能
+- [ ] 部分的に自動修正可能（{理由}）
+- [ ] 手動修正必要
+
+## 効果
+
+### 定量効果
+
+- チェック可能項目: +{N}項目
+- 機械的検出可能なバグ: {種類}
+- ドキュメント自動生成: {範囲}
+
+### 定性効果
+
+- {効果1: コード統一性}
+- {効果2: 新規参画者の学習コスト削減}
+- {効果3: レビュー負荷軽減}
+
+## 代替案
+
+### 代替案A: {名前}
+
+{概要}
+
+**Pros**: {利点}
+**Cons**: {欠点}
+
+### 採用理由
+
+{提案案を採用する理由}
+
+## 関連
+
+- 既存ルール: {関連する既存ルール}
+- ADR: {関連するADR}
+- Issue: {関連するIssue}
+
+---
+
+## Checklist
+
+- [ ] 現状の変動パターンを全て把握
+- [ ] 規約が明確で例外なく適用可能
+- [ ] チェックロジックが実装可能
+- [ ] 移行コストが許容範囲
+- [ ] 効果が移行コストを上回る

package/plugin/shirokuma-skills-en/skills/codebase-rule-discovery/templates/rule-proposal.md

@@ -0,0 +1,148 @@
+# Rule Proposal Template
+
+Use this template when proposing a new lint rule for shirokuma-docs.
+
+---
+
+# Rule Proposal: {rule-name}
+
+**Date**: YYYY-MM-DD
+**Category**: {Structural | Quality | Framework | Documentation}
+**Priority**: {P0 | P1 | P2}
+
+## Pattern Description
+
+{What pattern was discovered and why it matters}
+
+## Occurrences
+
+| App | Count | Example |
+|-----|-------|---------|
+| admin | X | `lib/actions/posts.ts:10` |
+| public | X | `lib/actions/comments.ts:5` |
+| web | X | `lib/actions/sessions.ts:15` |
+| mcp | X | `src/tools/entity.ts:20` |
+| shirokuma | X | `src/commands/lint.ts:30` |
+
+**Total**: X occurrences across Y apps
+
+## Inconsistencies Found
+
+{List deviations from the expected pattern}
+
+- App `admin`: {deviation description}
+- App `web`: {deviation description}
+
+## Proposed Rule
+
+### Specification
+
+```yaml
+rule:
+  id: "{rule-name}"
+  severity: "{error | warning | info}"
+  description: "{What the rule checks}"
+  fixable: {true | false}
+
+  options:
+    option1: value
+    option2: value
+```
+
+### Detection Logic
+
+```
+1. Find {pattern}
+2. Check {condition}
+3. Report if {violation}
+```
+
+### Auto-fix (if applicable)
+
+```
+1. {Fix step 1}
+2. {Fix step 2}
+```
+
+## Implementation Sketch
+
+```typescript
+import type { LintRule, LintIssue } from "../types.js";
+
+export const {ruleName}Rule: LintRule = {
+  id: "{rule-name}",
+  severity: "{severity}",
+  description: "{description}",
+
+  check(file: SourceFile, allFiles: SourceFile[]): LintIssue[] {
+    const issues: LintIssue[] = [];
+
+    // TODO: Implementation
+    // 1. Parse file content
+    // 2. Find pattern occurrences
+    // 3. Check for violations
+    // 4. Report issues
+
+    return issues;
+  }
+};
+```
+
+## Configuration
+
+```yaml
+# shirokuma-docs.config.yaml
+lintQuality:
+  {ruleName}:
+    enabled: true
+    severity: "{severity}"
+    # rule-specific options
+    option1: value
+```
+
+## Test Cases
+
+### Should Pass
+
+```typescript
+// Valid code example
+{valid code}
+```
+
+### Should Fail
+
+```typescript
+// Invalid code example
+{invalid code}
+```
+
+### Edge Cases
+
+- {Edge case 1}
+- {Edge case 2}
+
+## Priority Justification
+
+**P0**: {Critical - blocks deployment or causes bugs}
+**P1**: {Important - improves quality/consistency}
+**P2**: {Nice to have - minor improvements}
+
+{Explain why this priority was chosen}
+
+## Related
+
+- Existing rules: {related existing rules}
+- ADR: {related ADR if any}
+- Issue: {related issue if any}
+
+---
+
+## Checklist
+
+- [ ] Pattern validated across all apps
+- [ ] Occurrence counts documented
+- [ ] Inconsistencies identified
+- [ ] Implementation sketch provided
+- [ ] Test cases defined
+- [ ] Priority justified
+- [ ] Not duplicating existing rule

package/plugin/shirokuma-skills-en/skills/codebase-rule-discovery/workflows/analyze-codebase.md

@@ -0,0 +1,212 @@
+# Codebase Analysis Workflow
+
+Step-by-step workflow for discovering patterns across applications.
+
+## Prerequisites
+
+- Access to all target applications
+- shirokuma-docs installed
+- Understanding of [discovery-categories.md](../patterns/discovery-categories.md)
+
+## Workflow
+
+### Phase 1: Preparation
+
+#### 1.1 Define Scope
+
+```bash
+# Full analysis
+APPS="admin public"
+PATHS="nextjs-tdd-blog-cms/apps/admin nextjs-tdd-blog-cms/apps/public"
+
+# Specific category
+CATEGORY="error-handling"  # or: naming, types, async, jsdoc, etc.
+```
+
+#### 1.2 Check Existing Rules
+
+```bash
+ls shirokuma-docs/src/lint/rules/
+```
+
+Avoid duplicating:
+- server-action-structure.ts
+- annotation-required.ts
+- testdoc-*.ts
+
+### Phase 2: Data Collection
+
+#### 2.1 Run Pattern Counts
+
+For each pattern in discovery-categories.md:
+
+```bash
+# Template
+echo "=== Pattern: {name} ==="
+for app in $PATHS; do
+  count=$(grep -rn "PATTERN" "$app" --include="*.ts" 2>/dev/null | wc -l)
+  echo "$app: $count"
+done
+```
+
+#### 2.2 Collect Examples
+
+```bash
+# Get first 3 examples per app
+for app in $PATHS; do
+  echo "--- $app ---"
+  grep -rn "PATTERN" "$app" --include="*.ts" 2>/dev/null | head -3
+done
+```
+
+#### 2.3 Record in Matrix
+
+| Pattern | Admin | Public |
+|---------|-------|--------|
+| try-catch | X | X |
+| console.error | X | X |
+| ... | ... | ... |
+
+### Phase 3: Analysis
+
+#### 3.1 Identify Consistency
+
+Consistent pattern (good candidate for rule):
+- Same approach in 3+ apps
+- High occurrence count (>10 per app)
+
+#### 3.2 Identify Inconsistencies
+
+```
+App A: pattern X (100%)
+App B: pattern X (80%) + pattern Y (20%) ← Inconsistency!
+```
+
+#### 3.3 Identify Missing Patterns
+
+```
+App A: pattern present
+App B: pattern present
+App C: pattern MISSING ← Candidate for required rule
+```
+
+### Phase 4: Prioritization
+
+#### Priority Matrix
+
+| Criterion | P0 | P1 | P2 |
+|-----------|----|----|-----|
+| Bug potential | High | Medium | Low |
+| Occurrence | >100 | 50-100 | <50 |
+| Inconsistency | Critical | Moderate | Minor |
+| Fix complexity | Auto-fix | Semi-auto | Manual |
+
+#### Decision Tree
+
+```
+Is it a security/auth issue?
+├─ Yes → P0
+└─ No
+   Does it cause runtime bugs?
+   ├─ Yes → P0
+   └─ No
+      Is it consistency issue across apps?
+      ├─ Yes, >50 occurrences → P1
+      └─ No → P2
+```
+
+### Phase 5: Proposal Generation
+
+#### 5.1 Use Template
+
+Copy [templates/rule-proposal.md](../templates/rule-proposal.md)
+
+#### 5.2 Fill Sections
+
+1. **Pattern Description**: What you found
+2. **Occurrences**: Counts from Phase 2
+3. **Inconsistencies**: From Phase 3
+4. **Proposed Rule**: Detection logic
+5. **Implementation**: Code sketch
+6. **Priority**: From Phase 4
+
+#### 5.3 Validate
+
+- [ ] Not duplicating existing rule
+- [ ] Occurrence count >10 total
+- [ ] Clear detection logic
+- [ ] Auto-fix feasibility assessed
+
+### Phase 6: Output
+
+#### 6.1 Save Report
+
+```bash
+# Save report to GitHub Discussions (Research category)
+shirokuma-docs discussions create \
+  --category Research \
+  --title "[Research] Rule Discovery: ${CATEGORY}" \
+  --body "# Rule Discovery Report: ${CATEGORY}
+..."
+```
+
+#### 6.2 Link to Future Plans (if applicable)
+
+For rules that relate to planned features:
+- Check GitHub Discussions (Ideas category) for relevant proposals
+- Link to GitHub Projects for roadmap tracking
+
+#### 6.3 Create Follow-up Issue
+
+Create a GitHub Issue if the proposed rule requires shirokuma-docs implementation.
+
+## Quick Commands Reference
+
+```bash
+# Error handling patterns
+grep -rn "try {" apps/ --include="*.ts" | wc -l
+grep -rn "catch.*{" apps/ --include="*.ts" | wc -l
+grep -rn "console.error\|logger.error" apps/ --include="*.ts" | wc -l
+
+# Type safety
+grep -rn ": any\|as any" apps/ --include="*.ts" | wc -l
+
+# Async patterns
+grep -rn "async function\|async (" apps/ --include="*.ts" | wc -l
+grep -rn "\.then(" apps/ --include="*.ts" | wc -l
+
+# JSDoc coverage
+grep -rn "^/\*\*" apps/ --include="*.ts" | wc -l
+grep -rn "@param" apps/ --include="*.ts" | wc -l
+
+# Naming patterns
+find apps/ -name "*.ts" | xargs basename -a | sort | uniq -c | sort -rn | head -20
+
+# Export patterns
+grep -r "^export default" apps/ --include="*.ts" | wc -l
+grep -r "^export function" apps/ --include="*.ts" | wc -l
+```
+
+## Output Format
+
+```markdown
+# Rule Discovery Report: {Category}
+
+**Date**: YYYY-MM-DD
+**Apps Analyzed**: admin, public
+**Patterns Found**: X
+**Proposed Rules**: Y
+
+## Summary
+
+| Pattern | Occurrences | Consistency | Priority |
+|---------|-------------|-------------|----------|
+| {name} | X | High/Med/Low | P0/P1/P2 |
+
+## Proposals
+
+### 1. {Rule Name}
+[Link to full proposal]
+
+...
+```