@ranimontagna/agent-toolkit 0.1.6 → 0.1.9

package/skills/general/code-reviewer/rules/correctness-error-handling.md

@@ -0,0 +1,279 @@
+---
+title: Proper Error Handling
+impact: HIGH
+category: correctness
+tags: errors, exceptions, reliability
+---
+
+# Proper Error Handling
+
+Always handle errors explicitly. Don't use bare except clauses or ignore errors silently. Provide helpful error messages.
+
+## Why This Matters
+
+Proper error handling:
+- Prevents silent failures
+- Aids debugging with clear messages
+- Allows graceful degradation
+- Improves user experience
+- Enables error monitoring/alerting
+
+## ❌ Incorrect
+
+### Bare Except Clause
+```python
+# ❌ Catches everything, including KeyboardInterrupt, SystemExit
+try:
+    result = risky_operation()
+except:
+    pass  # Silent failure, no idea what went wrong
+```
+
+### Generic Exception Without Context
+```python
+# ❌ Too generic, loses error information
+try:
+    data = fetch_user(user_id)
+    process(data)
+    save_result()
+except Exception:
+    print("Error occurred")  # Which operation failed? Why?
+```
+
+### Ignoring Specific Errors
+```python
+# ❌ Ignoring errors entirely
+try:
+    config = json.loads(config_file.read())
+except json.JSONDecodeError:
+    pass  # App continues with undefined 'config'
+```
+
+## ✅ Correct
+
+### Catch Specific Exceptions
+```python
+# ✅ Handle specific errors appropriately
+try:
+    config = json.loads(config_file.read())
+except json.JSONDecodeError as e:
+    logger.error(f"Invalid JSON in config file: {e}")
+    # Provide sensible default
+    config = get_default_config()
+except FileNotFoundError:
+    logger.warning("Config file not found, using defaults")
+    config = get_default_config()
+```
+
+### Provide Context in Error Messages
+```python
+# ✅ Clear, actionable error messages
+def  get_user(user_id: int) -> User:
+    try:
+        response = requests.get(f"{API_URL}/users/{user_id}", timeout=5)
+        response.raise_for_status()
+        return User(**response.json())
+    except requests.Timeout:
+        raise ValueError(
+            f"Timeout fetching user {user_id} from {API_URL}. "
+            "Check network connection or increase timeout."
+        )
+    except requests.HTTPError as e:
+        if e.response.status_code == 404:
+            raise UserNotFoundError(f"User {user_id} does not exist")
+        raise ValueError(f"HTTP error fetching user {user_id}: {e}")
+    except json.JSONDecodeError:
+        raise ValueError(f"Invalid JSON response for user {user_id}")
+```
+
+### Re-raise with Context
+```python
+# ✅ Add context while preserving stack trace
+try:
+    process_batch(items)
+except ValidationError as e:
+    # Add context and re-raise
+    raise ValidationError(
+        f"Batch processing failed for {len(items)} items: {e}"
+    ) from e
+```
+
+## JavaScript/TypeScript
+
+### ❌ Catching Without Specificity
+```javascript
+// ❌ No error handling
+async function fetchUser(id) {
+  const response = await fetch(`/api/users/${id}`);
+  return response.json();  // What if fetch fails? What if not JSON?
+}
+
+// ❌ Generic catch
+try {
+  const user = await fetchUser(id);
+} catch (error) {
+  console.log('Error');  // Which error? From where?
+}
+```
+
+### ✅ Explicit Error Handling
+```typescript
+// ✅ Proper error handling with types
+class UserNotFoundError extends Error {
+  constructor(userId: string) {
+    super(`User ${userId} not found`);
+    this.name = 'UserNotFoundError';
+  }
+}
+
+async function fetchUser(id: string): Promise<User> {
+  let response: Response;
+  
+  try {
+    response = await fetch(`/api/users/${id}`, {
+      signal: AbortSignal.timeout(5000)
+    });
+  } catch (error) {
+    if (error instanceof DOMException && error.name === 'TimeoutError') {
+      throw new Error(`Timeout fetching user ${id}`);
+    }
+    throw new Error(`Network error fetching user ${id}: ${error}`);
+  }
+  
+  if (!response.ok) {
+    if (response.status === 404) {
+      throw new UserNotFoundError(id);
+    }
+    throw new Error(`HTTP ${response.status} fetching user ${id}`);
+  }
+  
+  try {
+    return await response.json();
+  } catch (error) {
+    throw new Error(`Invalid JSON response for user ${id}`);
+  }
+}
+
+// Usage
+try {
+  const user = await fetchUser(userId);
+  displayUser(user);
+} catch (error) {
+  if (error instanceof UserNotFoundError) {
+    showNotFoundMessage();
+  } else {
+    logger.error('Failed to load user:', error);
+    showErrorMessage('Unable to load user. Please try again.');
+  }
+}
+```
+
+## Error Handling Patterns
+
+### Result Type (Rust-inspired)
+```typescript
+type Result<T, E = Error> = 
+  | { ok: true; value: T }
+  | { ok: false; error: E };
+
+function parseConfig(json: string): Result<Config> {
+  try {
+    const config = JSON.parse(json);
+    return { ok: true, value: config };
+  } catch (error) {
+    return { ok: false, error: new Error(`Invalid config: ${error}`) };
+  }
+}
+
+// Usage
+const result = parseConfig(configString);
+if (result.ok) {
+  useConfig(result.value);
+} else {
+  logger.error(result.error);
+  useDefaultConfig();
+}
+```
+
+### Custom Error Classes
+```python
+class DatabaseError(Exception):
+    """Base class for database errors."""
+    pass
+
+class ConnectionError(DatabaseError):
+    """Database connection failed."""
+    pass
+
+class QueryError(DatabaseError):
+    """Query execution failed."""
+    def __init__(self, query: str, original_error: Exception):
+        self.query = query
+        self.original_error = original_error
+        super().__init__(f"Query failed: {query[:100]}... Error: {original_error}")
+
+# Usage
+try:
+    db.execute(query)
+except psycopg2.OperationalError as e:
+    raise ConnectionError(f"Cannot connect to database: {e}") from e
+except psycopg2.Error as e:
+    raise QueryError(query, e) from e
+```
+
+## Logging Errors
+
+```python
+import logging
+
+logger = logging.getLogger(__name__)
+
+try:
+    result = complex_operation()
+except ValueError as e:
+    logger.error(
+        "Operation failed",
+        exc_info=True,  # Include stack trace
+        extra={
+            'user_id': user_id,
+            'operation': 'complex_operation',
+            'input_data': sanitized_data
+        }
+    )
+    raise
+```
+
+## Best Practices
+
+- [ ] **Catch specific exceptions** (not bare `except` or generic `Exception`)
+- [ ] **Provide context** in error messages (what failed, why, how to fix)
+- [ ] **Log errors** with relevant details
+- [ ] **Don't silently ignore errors**
+- [ ] **Use custom exception classes** for domain errors
+- [ ] **Include stack traces** in logs (but not user-facing messages)
+- [ ] **Handle errors at appropriate level** (don't catch too early)
+- [ ] **Clean up resources** (use context managers/try-finally)
+
+## Monitoring & Alerting
+
+```python
+# Integration with error tracking
+import sentry_sdk
+
+try:
+    process_payment(order)
+except PaymentError as e:
+    sentry_sdk.capture_exception(e)
+    sentry_sdk.set_context("order", {
+        "order_id": order.id,
+        "amount": order.total,
+        "user_id": order.user_id
+    })
+    raise
+```
+
+## References
+
+- [Python Exception Handling Best Practices](https://docs.python.org/3/tutorial/errors.html)
+- [Error Handling in JavaScript](https://javascript.info/try-catch)
+- [Sentry Error Monitoring](https://sentry.io/)

package/skills/general/code-reviewer/rules/maintainability-naming.md

@@ -0,0 +1,149 @@
+---
+title: Use Meaningful Variable Names
+impact: MEDIUM
+category: maintainability
+tags: naming, readability, code-quality
+---
+
+# Use Meaningful Variable Names
+
+Choose descriptive, intention-revealing names. Avoid single letters (except loop counters), abbreviations, and generic names.
+
+## Why This Matters
+
+Code is read 10x more than it's written. Clear names:
+- Make code self-documenting
+- Reduce cognitive load
+- Prevent bugs from misunderstanding
+- Enable easier refactoring
+
+## ❌ Incorrect
+
+```python
+# ❌ Cryptic, meaningless
+def calc(x, y, z):
+    tmp = x * y
+    res = tmp + z
+    return res
+
+# ❌ Too generic
+data = fetch_data()
+result = process(data)
+output = format(result)
+
+# ❌ Confusing abbreviations
+usr_nm = input()
+acc_bal = get_bal(usr_nm)
+```
+
+## ✅ Correct
+
+```python
+# ✅ Clear, descriptive
+def calculate_total_price(item_price: float, quantity: int, tax_rate: float) -> float:
+    """Calculate total price including tax."""
+    subtotal = item_price * quantity
+    total_with_tax = subtotal + (subtotal * tax_rate)
+    return total_with_tax
+
+# ✅ Intention-revealing
+customer_orders = fetch_customer_orders(customer_id)
+validated_orders = validate_orders(customer_orders)
+order_confirmation_email = format_confirmation_email(validated_orders)
+
+# ✅ Full words
+username = input("Enter username: ")
+account_balance = get_account_balance(username)
+```
+
+## Naming Conventions by Language
+
+### Python (PEP 8)
+```python
+# Variables & functions: snake_case
+user_count = 10
+def calculate_average(): pass
+
+# Classes: PascalCase
+class UserAccount: pass
+
+# Constants: UPPER_SNAKE_CASE
+MAX_RETRY_ATTEMPTS = 3
+```
+
+### JavaScript/TypeScript
+```javascript
+// Variables & functions: camelCase
+const userCount = 10;
+function calculateAverage() {}
+
+// Classes: PascalCase
+class UserAccount {}
+
+// Constants: UPPER_SNAKE_CASE or camelCase
+const MAX_RETRY_ATTEMPTS = 3;
+const maxRetryAttempts = 3;  // Also acceptable
+```
+
+### Booleans
+```python
+# Use is_, has_, can_ prefixes
+is_active = True
+has_permission = check_permission()
+can_edit = user.role == "admin"
+
+# Not: active, permission, editable
+```
+
+## Context Matters
+
+### Loop Variables
+```python
+# ❌ Generic in complex loop
+for i in users:
+    for j in i.orders:
+        process(j)
+
+# ✅ Descriptive
+for user in users:
+    for order in user.orders:
+        process_order(order)
+
+# ✅ Single letter OK for simple index
+for i in range(10):
+    print(i)
+```
+
+### Scope-Appropriate Names
+```python
+# Short scope: concise OK
+def validate(email):
+    # 'email' is clear in this small function
+    return '@' in email and '.' in email
+
+# Long scope: more descriptive
+class UserAuthenticationService:
+    def __init__(self):
+        # Longer, clearer for class-level
+        self.failed_login_attempts = {}
+        self.account_lockout_duration_seconds = 300
+```
+
+## Avoid Ambiguity
+
+```python
+# ❌ Ambiguous
+def get_data(id):
+    return data[id]
+
+# What data? What ID?
+
+# ✅ Specific
+def get_user_by_id(user_id: int) -> User:
+    return users_cache[user_id]
+```
+
+## References
+
+- [PEP 8 - Python Naming Conventions](https://peps.python.org/pep-0008/#naming-conventions)
+- [Clean Code by Robert Martin](https://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882)

package/skills/general/code-reviewer/rules/maintainability-type-hints.md

@@ -0,0 +1,93 @@
+---
+title: Add Type Hints
+impact: MEDIUM
+category: maintainability
+tags: types, python, typescript, type-safety
+---
+
+# Add Type Hints
+
+Use type annotations to make code self-documenting and catch errors early.
+
+## Why This Matters
+
+Type hints provide:
+- **Static analysis** - catch bugs before runtime
+- **Better IDE support** - autocomplete, refactoring
+- **Documentation** - types explain intent
+- **Confidence** - easier refactoring
+
+##❌ Incorrect
+
+```python
+# ❌ No type hints
+def get_user(id):
+    return users.get(id)
+
+def process_order(order, discount):
+    if discount:
+        return order['total'] * (1 - discount)
+    return order['total']
+```
+
+## ✅ Correct
+
+```python
+# ✅ Full type hints
+from typing import Optional, Dict, Any
+
+def get_user(id: int) -> Optional[Dict[str, Any]]:
+    """Fetch user by ID.
+    
+    Args:
+        id: User ID
+        
+    Returns:
+        User dict or None if not found
+    """
+    return users.get(id)
+
+def process_order(order: Dict[str, Any], discount: Optional[float] = None) -> float:
+    """Calculate order total with optional discount.
+    
+    Args:
+        order: Order dictionary with 'total' key
+        discount: Discount rate (0.0-1.0), e.g. 0.1 for 10% off
+        
+    Returns:
+        Final price after discount
+    """
+    if discount:
+        return order['total'] * (1 - discount)
+    return order['total']
+```
+
+## TypeScript
+
+```typescript
+// ✅ Explicit types
+interface User {
+  id: number;
+  name: string;
+  email: string;
+}
+
+function getUser(id: number): User | null {
+  return users.get(id) ?? null;
+}
+
+function processOrder(
+  order: { total: number },
+  discount?: number
+): number {
+  if (discount) {
+    return order.total * (1 - discount);
+  }
+  return order.total;
+}
+```
+
+## References
+
+- [Python Type Hints](https://docs.python.org/3/library/typing.html)
+- [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/intro.html)