devflow-kit 0.9.0 → 1.0.0

package/plugins/devflow-code-review/skills/documentation-patterns/references/detection.md

@@ -0,0 +1,190 @@
+# Documentation Detection Patterns
+
+Bash commands and search patterns for finding documentation issues.
+
+---
+
+## Finding Missing Documentation
+
+### Functions Without JSDoc
+
+```bash
+# Find exported functions without JSDoc comment above
+grep -rn "export function\|export async function" --include="*.ts" | \
+  xargs -I {} sh -c 'grep -B1 "{}" | grep -v "/\*\*"'
+
+# Find all exports, check for docs
+grep -rn "^export " --include="*.ts" -A1 | grep -v "^--$" | grep -v "/\*\*"
+```
+
+### Classes Without Documentation
+
+```bash
+# Find classes without JSDoc
+grep -rn "^export class\|^class " --include="*.ts" | \
+  while read line; do
+    file=$(echo "$line" | cut -d: -f1)
+    linenum=$(echo "$line" | cut -d: -f2)
+    prev=$((linenum - 1))
+    if ! sed -n "${prev}p" "$file" | grep -q "\*/"; then
+      echo "$line"
+    fi
+  done
+```
+
+### Public Methods Without Documentation
+
+```bash
+# Find public methods (not private/protected) without JSDoc
+grep -rn "^\s*public\|^\s*async\s\+[a-z]" --include="*.ts" | \
+  grep -v "private\|protected\|constructor"
+```
+
+---
+
+## Finding Outdated Documentation
+
+### TODO/FIXME Comments
+
+```bash
+# Find all TODO/FIXME comments
+grep -rn "TODO\|FIXME\|HACK\|XXX" --include="*.ts" --include="*.tsx"
+
+# Find TODOs older than 6 months (requires git)
+git log --since="6 months ago" --all --pretty=format: --name-only --diff-filter=D | \
+  xargs -I {} grep -l "TODO\|FIXME" {} 2>/dev/null
+```
+
+### Deprecated References
+
+```bash
+# Find @deprecated, @see, @link annotations that may be stale
+grep -rn "@see\|@link\|@deprecated" --include="*.ts"
+
+# Find references to potentially removed functions
+grep -rn "@see.*#[a-zA-Z]" --include="*.ts"
+```
+
+### Comment-Code Drift Indicators
+
+```bash
+# Find comments with numbers that might drift
+grep -rn "// .*[0-9]\+.*times\|// .*[0-9]\+.*retries\|// .*[0-9]\+.*max" --include="*.ts"
+
+# Find hardcoded numbers near comments
+grep -rn "for.*[0-9]\+\|while.*[0-9]\+\|< [0-9]\+\|<= [0-9]\+" --include="*.ts" -B2
+```
+
+---
+
+## Finding Documentation Smells
+
+### Magic Numbers (Need Comments)
+
+```bash
+# Find magic numbers that likely need explanation
+grep -rn "[^a-zA-Z_][0-9]\{3,\}[^a-zA-Z_0-9]" --include="*.ts" | \
+  grep -v "const\|enum\|type\|interface\|import"
+
+# Find percentages, timeouts, limits
+grep -rn "[0-9]\+%\|[0-9]\+ms\|[0-9]\+s\|Timeout\|Limit" --include="*.ts"
+```
+
+### Comments Explaining "What"
+
+```bash
+# Find likely "what" comments (loop, check, get, set, etc.)
+grep -rn "// [Ll]oop\|// [Cc]heck\|// [Gg]et\|// [Ss]et\|// [Aa]dd\|// [Rr]emove" --include="*.ts"
+
+# Find single-word comments
+grep -rn "// [A-Z][a-z]\+$" --include="*.ts"
+```
+
+### Empty Catch Blocks (Need Explanation)
+
+```bash
+# Find empty or minimal catch blocks
+grep -rn "catch.*{" --include="*.ts" -A2 | grep -E "^\s*}\s*$|// ignore"
+```
+
+---
+
+## README/Changelog Checks
+
+### README Freshness
+
+```bash
+# Check if README mentions removed functions
+# First, find removed exports in recent commits
+git diff HEAD~50..HEAD --name-only -- "*.ts" | \
+  xargs -I {} git diff HEAD~50..HEAD -- {} | \
+  grep "^-export" | cut -d' ' -f3 | \
+  while read func; do
+    grep -l "$func" README.md 2>/dev/null && echo "README references removed: $func"
+  done
+```
+
+### Changelog Completeness
+
+```bash
+# Find recent breaking changes not in CHANGELOG
+git log --oneline --since="1 month ago" | grep -i "breaking\|remove\|deprecate"
+
+# Check CHANGELOG has recent version
+head -20 CHANGELOG.md
+```
+
+### Example Code Validation
+
+```bash
+# Extract code blocks from README and try to validate imports
+grep -A10 '```typescript\|```javascript' README.md | \
+  grep "import\|require" | \
+  while read line; do
+    # Check if imported module/function still exists
+    echo "Checking: $line"
+  done
+```
+
+---
+
+## Automated Checks
+
+### Pre-commit Hook
+
+```bash
+#!/bin/bash
+# Add to .git/hooks/pre-commit
+
+# Check for undocumented exports
+undocumented=$(grep -rn "^export function\|^export class" --include="*.ts" | \
+  while read line; do
+    file=$(echo "$line" | cut -d: -f1)
+    linenum=$(echo "$line" | cut -d: -f2)
+    prev=$((linenum - 1))
+    if ! sed -n "${prev}p" "$file" | grep -q "\*/"; then
+      echo "$line"
+    fi
+  done)
+
+if [ -n "$undocumented" ]; then
+  echo "ERROR: Undocumented exports found:"
+  echo "$undocumented"
+  exit 1
+fi
+```
+
+### CI Check
+
+```yaml
+# Add to CI pipeline
+documentation-check:
+  script:
+    - npm run docs:check  # Runs typedoc or similar
+    - |
+      # Check for stale TODOs
+      old_todos=$(grep -rn "TODO" --include="*.ts" | wc -l)
+      if [ "$old_todos" -gt 50 ]; then
+        echo "WARNING: $old_todos TODO comments found"
+      fi
+```

package/plugins/devflow-code-review/skills/documentation-patterns/references/patterns.md

@@ -0,0 +1,189 @@
+# Correct Documentation Patterns
+
+Extended examples of proper documentation. See parent `SKILL.md` for brief examples and severity guidelines.
+
+---
+
+## Code Documentation Patterns
+
+### Proper JSDoc for Complex Functions
+
+```typescript
+/**
+ * Calculates prorated billing amount when switching plans mid-cycle.
+ *
+ * @param plan - The new plan to prorate to
+ * @param startDate - When the new plan starts
+ * @param endDate - End of current billing cycle
+ * @param previousPlan - Optional previous plan for credit calculation
+ * @returns Prorated amount in cents (can be negative for downgrades)
+ *
+ * @example
+ * // Upgrading mid-month
+ * calculateProratedAmount(premiumPlan, new Date('2024-01-15'), new Date('2024-01-31'))
+ * // Returns: 1645 (cents)
+ *
+ * @throws {InvalidDateRangeError} If startDate is after endDate
+ */
+export function calculateProratedAmount(
+  plan: Plan,
+  startDate: Date,
+  endDate: Date,
+  previousPlan?: Plan
+): number {
+  // ...
+}
+```
+
+**Key elements**: Purpose, all params, return type with units, example usage, error conditions.
+
+### Comments That Explain "Why"
+
+```typescript
+// Filter to active users only - inactive users should not receive
+// promotional emails per GDPR consent requirements
+const activeUsers = users.filter(u => u.active);
+```
+
+**Key elements**: Business reason (GDPR), not mechanical description.
+
+### Algorithm Documentation
+
+```typescript
+/**
+ * Schedules tasks using weighted shortest job first (WSJF) algorithm.
+ *
+ * Priority score = (priority * urgency) / duration
+ * Higher scores are scheduled first.
+ *
+ * Tasks are placed starting 1.5x their duration before deadline
+ * to allow buffer for overruns.
+ *
+ * @see https://www.scaledagileframework.com/wsjf/
+ */
+function schedule(tasks: Task[]): Schedule {
+  // ...
+}
+```
+
+**Key elements**: Algorithm name, formula explanation, rationale for magic numbers, external reference.
+
+---
+
+## API Documentation Patterns
+
+### Complete Parameter Documentation
+
+```typescript
+/**
+ * Creates a new subscription for a user.
+ *
+ * @param userId - The unique identifier of the user
+ * @param planId - The plan to subscribe to (from /plans endpoint)
+ * @param options - Optional configuration
+ * @param options.trialDays - Number of trial days (default: 0, max: 30)
+ * @param options.couponCode - Discount coupon to apply
+ * @param options.startDate - When to start (default: now)
+ *
+ * @returns The created subscription with payment details
+ *
+ * @throws {UserNotFoundError} If userId doesn't exist
+ * @throws {PlanNotFoundError} If planId doesn't exist
+ * @throws {InvalidCouponError} If coupon is expired or invalid
+ */
+async function createSubscription(
+  userId: string,
+  planId: string,
+  options?: SubscriptionOptions
+): Promise<Subscription>;
+```
+
+**Key elements**: All params including nested options, defaults, constraints, all error types.
+
+### Return Value Documentation
+
+```typescript
+/**
+ * Fetches aggregated analytics data for the date range.
+ *
+ * @param range - Start and end dates for the query
+ * @returns Analytics data including:
+ *   - totalVisitors: Unique visitor count
+ *   - pageViews: Total page view count
+ *   - bounceRate: Percentage (0-100) of single-page sessions
+ *   - avgSessionDuration: Average session length in seconds
+ *   - topPages: Array of {path, views} sorted by views desc
+ */
+async function getAnalytics(range: DateRange): Promise<Analytics>;
+```
+
+**Key elements**: Shape of return object, units (percentage, seconds), sorting order.
+
+### Error Documentation
+
+```typescript
+/**
+ * Transfers funds between accounts.
+ *
+ * @throws {InsufficientFundsError} If source account balance < amount
+ * @throws {AccountNotFoundError} If either account doesn't exist
+ * @throws {AccountFrozenError} If either account is frozen
+ * @throws {TransferLimitError} If amount exceeds daily transfer limit
+ * @throws {SameAccountError} If from === to
+ */
+async function transferFunds(from: string, to: string, amount: number): Promise<void>;
+```
+
+**Key elements**: All possible error types with conditions that trigger them.
+
+---
+
+## Alignment Patterns
+
+### Constants Instead of Magic Numbers
+
+```typescript
+const MAX_RETRIES = 5;
+
+// Retries up to MAX_RETRIES times with exponential backoff
+async function fetchWithRetry(url: string) {
+  for (let i = 0; i < MAX_RETRIES; i++) { /* ... */ }
+}
+```
+
+**Key elements**: Named constant keeps comment and code in sync automatically.
+
+### Up-to-Date README
+
+```markdown
+## Installation
+npm install mypackage@^2.0.0
+
+## Usage
+import { newFunction } from 'mypackage';
+await newFunction({ /* new options */ });
+
+## Migration from v1
+See [MIGRATION.md](./MIGRATION.md) for upgrade instructions.
+```
+
+**Key elements**: Correct version, working examples, migration guidance.
+
+### Proper Changelog
+
+```markdown
+## [2.0.0] - 2024-01-15
+
+### Breaking Changes
+- `createUser()` now returns `Promise<Result<User>>` instead of `Promise<User>`
+- Removed deprecated `oldFunction()` - use `newFunction()` instead
+- Minimum Node.js version is now 18
+
+### Added
+- New `validateUser()` function for input validation
+
+### Changed
+- Improved error messages for authentication failures
+```
+
+**Key elements**: Breaking changes highlighted first, migration hints, categorized changes.

package/plugins/devflow-code-review/skills/documentation-patterns/references/violations.md

@@ -0,0 +1,163 @@
+# Documentation Violation Examples
+
+Extended examples of documentation anti-patterns. See parent `SKILL.md` for brief examples and severity guidelines.
+
+---
+
+## Code Documentation Violations
+
+### Missing Docstrings/JSDoc
+
+```typescript
+// VIOLATION: Complex function without documentation
+export function calculateProratedAmount(
+  plan: Plan,
+  startDate: Date,
+  endDate: Date,
+  previousPlan?: Plan
+): number {
+  // 50 lines of complex billing logic...
+}
+```
+
+**Why it's a problem**: Complex billing logic with edge cases (negative amounts for downgrades, credit calculations) is impossible to use correctly without documentation.
+
+### Outdated Comments
+
+```typescript
+// VIOLATION: Comment doesn't match code
+// Returns user's full name
+function getDisplayName(user: User): string {
+  return user.username;  // Actually returns username, not full name!
+}
+
+// VIOLATION: TODO that's been done
+// TODO: Add validation
+function processInput(input: string) {
+  if (!isValid(input)) throw new Error('Invalid');  // Validation exists!
+  // ...
+}
+```
+
+**Why it's a problem**: Misleading comments cause bugs when developers trust them over reading the code.
+
+### Comments Explaining "What" Instead of "Why"
+
+```typescript
+// VIOLATION: Describes what code does (obvious from code)
+// Loop through users
+for (const user of users) {
+  // Check if user is active
+  if (user.active) {
+    // Add user to list
+    activeUsers.push(user);
+  }
+}
+```
+
+**Why it's a problem**: These comments add noise without value. The code already says what it does.
+
+### Complex Code Without Explanation
+
+```typescript
+// VIOLATION: Magic algorithm without explanation
+function schedule(tasks: Task[]): Schedule {
+  return tasks
+    .sort((a, b) => (b.priority * b.urgency) / b.duration - (a.priority * a.urgency) / a.duration)
+    .reduce((schedule, task) => {
+      const slot = findSlot(schedule, task, task.deadline - task.duration * 1.5);
+      return slot ? addToSchedule(schedule, task, slot) : schedule;
+    }, emptySchedule());
+}
+```
+
+**Why it's a problem**: The WSJF algorithm and 1.5x buffer are non-obvious. Future maintainers will be confused or afraid to modify.
+
+---
+
+## API Documentation Violations
+
+### Missing Parameter Descriptions
+
+```typescript
+// VIOLATION: Parameters unexplained
+/**
+ * Creates a new subscription.
+ */
+async function createSubscription(
+  userId: string,
+  planId: string,
+  options?: SubscriptionOptions
+): Promise<Subscription>;
+```
+
+**Why it's a problem**: Callers don't know valid values for `planId`, what `options` are available, or constraints on parameters.
+
+### Missing Return Value Documentation
+
+```typescript
+// VIOLATION: Return shape unknown
+/**
+ * Fetches analytics data.
+ */
+async function getAnalytics(range: DateRange): Promise<Analytics>;
+```
+
+**Why it's a problem**: Consumers must read implementation to understand the shape of `Analytics`.
+
+### Missing Error Documentation
+
+```typescript
+// VIOLATION: Errors not documented
+async function transferFunds(from: string, to: string, amount: number): Promise<void>;
+```
+
+**Why it's a problem**: Callers don't know what errors to catch or handle. They'll either catch everything or miss important cases.
+
+---
+
+## Alignment Violations
+
+### Code-Comment Drift
+
+```typescript
+// BEFORE: Comment matches
+// Retries up to 3 times with exponential backoff
+async function fetchWithRetry(url: string) {
+  for (let i = 0; i < 3; i++) { /* ... */ }
+}
+
+// AFTER: Code changed, comment didn't
+// Retries up to 3 times with exponential backoff
+async function fetchWithRetry(url: string) {
+  for (let i = 0; i < 5; i++) { /* ... */ }  // Now 5 retries!
+}
+```
+
+**Why it's a problem**: Developers relying on the comment will expect different behavior than actual.
+
+### Stale README
+
+```markdown
+<!-- VIOLATION: README doesn't reflect reality -->
+
+## Installation
+npm install mypackage
+
+## Usage
+const { oldFunction } = require('mypackage');
+oldFunction(); // This function was removed!
+```
+
+**Why it's a problem**: New users follow outdated instructions and immediately hit errors.
+
+### Missing Changelog Entries
+
+```markdown
+<!-- VIOLATION: Breaking change not documented -->
+
+## [2.0.0] - 2024-01-15
+- Updated dependencies
+```
+
+**Why it's a problem**: Users upgrading have no warning about breaking changes and no migration path.