@sun-asterisk/sunlint 1.3.39 → 1.3.41

package/skill-assets/sunlint-code-quality/rules/typescript/C030-custom-error-classes.md

@@ -0,0 +1,60 @@
+---
+title: Use Custom Error Classes
+impact: HIGH
+impactDescription: enables proper error categorization and handling
+tags: error-handling, custom-errors, exceptions, patterns, quality
+---
+
+## Use Custom Error Classes
+
+Custom error classes enable proper error handling, categorization, and monitoring. They provide clear contracts for API consumers.
+
+**Incorrect (generic errors):**
+
+```typescript
+throw new Error("User not found");
+throw new Error("Invalid input");
+throw new Error("Database connection failed");
+```
+
+**Correct (custom error hierarchy):**
+
+```typescript
+// Base application error
+class AppError extends Error {
+  constructor(
+    message: string,
+    public readonly code: string,
+    public readonly statusCode: number = 500,
+    public readonly context?: Record<string, unknown>
+  ) {
+    super(message);
+    this.name = this.constructor.name;
+  }
+}
+
+// Specific errors
+class UserNotFoundError extends AppError {
+  constructor(userId: string) {
+    super(`User ${userId} not found`, 'USER_NOT_FOUND', 404, { userId });
+  }
+}
+
+class ValidationError extends AppError {
+  constructor(field: string, message: string) {
+    super(message, 'VALIDATION_ERROR', 400, { field });
+  }
+}
+
+// Usage
+throw new UserNotFoundError(userId);
+throw new ValidationError('email', 'Invalid email format');
+```
+
+**Benefits:**
+- Type-safe error handling
+- Automatic HTTP status mapping
+- Structured error context
+- Consistent error format
+
+**Tools:** Linter, Convention

package/skill-assets/sunlint-code-quality/rules/typescript/C033-separate-data-access.md

@@ -0,0 +1,69 @@
+---
+title: Separate Processing And Data Access
+impact: HIGH
+impactDescription: enables testable business logic
+tags: separation, repository, service, architecture, quality
+---
+
+## Separate Processing And Data Access
+
+Mixing business logic with database queries creates tight coupling and makes testing require real databases.
+
+**Incorrect (mixed concerns):**
+
+```typescript
+class OrderService {
+  async calculateDiscount(userId: string) {
+    // Business logic mixed with data access
+    const user = await db.query('SELECT * FROM users WHERE id = $1', [userId]);
+    const orders = await db.query('SELECT * FROM orders WHERE user_id = $1', [userId]);
+    
+    let discount = 0;
+    if (orders.length > 10) discount += 5;
+    if (user.isPremium) discount += 10;
+    
+    return discount;
+  }
+}
+```
+
+**Correct (separated layers):**
+
+```typescript
+// Repository - data access only
+class UserRepository {
+  async findById(userId: string): Promise<User | null> {
+    return db.query('SELECT * FROM users WHERE id = $1', [userId]);
+  }
+}
+
+class OrderRepository {
+  async findByUserId(userId: string): Promise<Order[]> {
+    return db.query('SELECT * FROM orders WHERE user_id = $1', [userId]);
+  }
+}
+
+// Service - business logic only
+class DiscountService {
+  constructor(
+    private userRepo: UserRepository,
+    private orderRepo: OrderRepository
+  ) {}
+
+  async calculateDiscount(userId: string): Promise<number> {
+    const user = await this.userRepo.findById(userId);
+    const orders = await this.orderRepo.findByUserId(userId);
+    
+    return this.computeDiscount(user, orders);
+  }
+
+  private computeDiscount(user: User | null, orders: Order[]): number {
+    let discount = 0;
+    if (orders.length > 10) discount += 5;
+    if (user?.isPremium) discount += 10;
+    return discount;
+  }
+}
+```
+
+**Tools:** Architectural review, Code Review

package/skill-assets/sunlint-code-quality/rules/typescript/C035-error-context-logging.md

@@ -0,0 +1,50 @@
+---
+title: Log All Relevant Context On Errors
+impact: HIGH
+impactDescription: enables quick debugging and incident response
+tags: error-handling, logging, context, debugging, quality
+---
+
+## Log All Relevant Context On Errors
+
+Context-rich logs enable quick debugging. Without proper context, finding root causes is like finding a needle in a haystack.
+
+**Incorrect (minimal context):**
+
+```typescript
+logger.error('Error occurred');
+logger.error(error.message);
+```
+
+**Correct (comprehensive context):**
+
+```typescript
+logger.error('Failed to process order', {
+  // What happened
+  error: error.message,
+  stack: error.stack,
+  errorCode: error.code,
+  
+  // Context
+  orderId: order.id,
+  userId: user.id,
+  requestId: ctx.requestId,
+  
+  // Input that caused the issue
+  orderItems: order.items.length,
+  totalAmount: order.total,
+  
+  // Timing
+  timestamp: new Date().toISOString(),
+  processingTimeMs: Date.now() - startTime
+});
+```
+
+**Essential context:**
+- Error details (message, stack, code)
+- Entity identifiers
+- Request/correlation IDs
+- Relevant input summary
+- Timing information
+
+**Tools:** Logging framework, Observability tools

package/skill-assets/sunlint-code-quality/rules/typescript/C041-no-hardcoded-secrets.md

@@ -0,0 +1,47 @@
+---
+title: No Hardcoded Secrets In Repo
+impact: HIGH
+impactDescription: prevents credential exposure
+tags: secrets, credentials, security, git, quality
+---
+
+## No Hardcoded Secrets In Repo
+
+Secrets in code are exposed to everyone with repo access and can be scraped by attackers.
+
+**Incorrect (secrets in code):**
+
+```typescript
+const API_KEY = 'sk-abc123xyz789';
+const DB_PASSWORD = 'admin123';
+
+fetch('https://api.stripe.com/v1/charges', {
+  headers: { 'Authorization': 'Bearer sk_live_xxx' }
+});
+```
+
+**Correct (environment/secrets manager):**
+
+```typescript
+// From environment
+const API_KEY = process.env.API_KEY;
+
+// From secrets manager
+const apiKey = await secretManager.getSecret('stripe-api-key');
+
+// Validation at startup
+if (!process.env.API_KEY) {
+  throw new Error('API_KEY environment variable is required');
+}
+```
+
+```gitignore
+# .gitignore
+.env
+.env.local
+*.pem
+*.key
+secrets/
+```
+
+**Tools:** GitLeaks, TruffleHog, pre-commit hooks

package/skill-assets/sunlint-code-quality/rules/typescript/C042-boolean-naming.md

@@ -0,0 +1,42 @@
+---
+title: Boolean Names Is/Has/Should
+impact: HIGH
+impactDescription: makes conditions instantly readable
+tags: naming, booleans, readability, quality
+---
+
+## Boolean Names Is/Has/Should
+
+Boolean prefixes make conditions instantly readable.
+
+**Incorrect (unclear boolean names):**
+
+```typescript
+const active = user.status === 'active';
+const admin = checkAdminRole(user);
+const items = cart.length > 0;
+const update = needsRefresh();
+```
+
+**Correct (boolean prefixes):**
+
+```typescript
+const isActive = user.status === 'active';
+const isAdmin = checkAdminRole(user);
+const hasItems = cart.length > 0;
+const shouldUpdate = needsRefresh();
+const canEdit = hasPermission(user, 'edit');
+const willExpire = expirationDate < tomorrow;
+```
+
+**Boolean prefixes:**
+
+| Prefix | Use For |
+|--------|---------|
+| `is` | State (isActive, isEnabled) |
+| `has` | Ownership (hasPermission, hasError) |
+| `should` | Decision (shouldUpdate, shouldRetry) |
+| `can` | Capability (canEdit, canDelete) |
+| `will` | Future (willExpire, willRetry) |
+
+**Tools:** Linter, Code Review

package/skill-assets/sunlint-code-quality/rules/typescript/C052-controller-parsing.md

@@ -0,0 +1,64 @@
+---
+title: Separate Parsing From Controllers
+impact: HIGH
+impactDescription: keeps controllers thin and focused
+tags: controller, parsing, transformation, patterns, quality
+---
+
+## Separate Parsing From Controllers
+
+Controllers should be thin - only handling HTTP concerns. Transformation logic should be extracted.
+
+**Incorrect (transformation in controller):**
+
+```typescript
+class UserController {
+  async getUser(req: Request, res: Response) {
+    const user = await this.userService.findById(req.params.id);
+    
+    // Transformation logic in controller
+    const response = {
+      id: user.id,
+      fullName: `${user.firstName} ${user.lastName}`,
+      email: user.email.toLowerCase(),
+      createdAt: format(user.createdAt, 'yyyy-MM-dd'),
+      age: differenceInYears(new Date(), user.birthDate)
+    };
+    
+    res.json(response);
+  }
+}
+```
+
+**Correct (separate mapper):**
+
+```typescript
+// Mapper/Transformer
+class UserMapper {
+  static toResponse(user: User): UserResponse {
+    return {
+      id: user.id,
+      fullName: `${user.firstName} ${user.lastName}`,
+      email: user.email.toLowerCase(),
+      createdAt: format(user.createdAt, 'yyyy-MM-dd'),
+      age: differenceInYears(new Date(), user.birthDate)
+    };
+  }
+}
+
+// Clean controller
+class UserController {
+  async getUser(req: Request, res: Response) {
+    const user = await this.userService.findById(req.params.id);
+    res.json(UserMapper.toResponse(user));
+  }
+}
+```
+
+**Benefits:**
+- Reusable transformation logic
+- Testable mappers
+- Clean controllers
+- Consistent response format
+
+**Tools:** Code review, Architecture rules

package/skill-assets/sunlint-code-quality/rules/typescript/C060-superclass-logic.md

@@ -0,0 +1,67 @@
+---
+title: Do Not Ignore Superclass Logic
+impact: HIGH
+impactDescription: ensures proper inheritance behavior
+tags: inheritance, override, superclass, oop, quality
+---
+
+## Do Not Ignore Superclass Logic
+
+When overriding methods, ensure superclass behavior is preserved unless explicitly intended otherwise.
+
+**Incorrect (ignoring superclass):**
+
+```typescript
+class BaseService {
+  async save(entity: Entity) {
+    this.validate(entity);
+    await this.beforeSave(entity);
+    await this.repository.save(entity);
+    await this.afterSave(entity);
+  }
+}
+
+class UserService extends BaseService {
+  async save(user: User) {
+    // Completely ignores validation, hooks, etc.
+    await this.repository.save(user);
+  }
+}
+```
+
+**Correct (calling super):**
+
+```typescript
+class UserService extends BaseService {
+  async save(user: User) {
+    // Add user-specific preprocessing
+    user.updatedAt = new Date();
+    
+    // Call superclass implementation
+    await super.save(user);
+    
+    // Add user-specific postprocessing
+    await this.updateSearchIndex(user);
+  }
+}
+```
+
+**When to skip super:**
+- Complete replacement is intentional
+- Base implementation doesn't apply
+- Document the reason clearly
+
+```typescript
+class UserService extends BaseService {
+  /**
+   * Override: Users require special validation,
+   * base validation is not applicable.
+   */
+  async save(user: User) {
+    await this.validateUser(user);
+    // Intentionally not calling super
+  }
+}
+```
+
+**Tools:** Static Analysis, Code Review

package/skill-assets/sunlint-code-quality/rules/typescript/C067-no-hardcoded-config.md

@@ -0,0 +1,52 @@
+---
+title: Do Not Hardcode Configuration
+impact: HIGH
+impactDescription: enables environment-specific deployments
+tags: configuration, environment, deployment, quality
+---
+
+## Do Not Hardcode Configuration
+
+Hardcoded config requires code changes to deploy to different environments.
+
+**Incorrect (hardcoded config):**
+
+```typescript
+const API_URL = 'https://api.production.example.com';
+const TIMEOUT = 5000;
+const MAX_FILE_SIZE = 10485760;
+```
+
+**Correct (externalized config):**
+
+```typescript
+// config.ts
+const config = {
+  api: {
+    url: process.env.API_URL || 'http://localhost:3000',
+    timeout: parseInt(process.env.API_TIMEOUT || '5000'),
+  },
+  upload: {
+    maxFileSize: parseInt(process.env.MAX_FILE_SIZE || '10485760'),
+  },
+  features: {
+    newDashboard: process.env.FEATURE_NEW_DASHBOARD === 'true',
+  },
+};
+
+// Validate at startup
+const required = ['API_URL', 'DATABASE_URL'];
+for (const envVar of required) {
+  if (!process.env[envVar]) {
+    throw new Error(`Missing: ${envVar}`);
+  }
+}
+
+export default config;
+
+// Usage
+import config from './config';
+fetch(`${config.api.url}/users`, { timeout: config.api.timeout });
+```
+
+**Tools:** dotenv, config libraries, Manual review

package/skill-assets/sunlint-code-quality/rules/typescript/S003-open-redirect.md

@@ -0,0 +1,76 @@
+---
+title: URL Redirects Must Be In Allow List
+impact: LOW
+impactDescription: prevents open redirect vulnerabilities
+tags: redirect, url, allow-list, validation, security
+---
+
+## URL Redirects Must Be In Allow List
+
+Open redirect vulnerabilities allow attackers to redirect users to malicious sites, often used in phishing attacks.
+
+**Incorrect (unvalidated redirect URL):**
+
+```typescript
+// Open redirect vulnerability
+app.get('/redirect', (req, res) => {
+  const url = req.query.url;
+  res.redirect(url);  // Attacker: ?url=https://evil.com
+});
+
+// Partial validation (can be bypassed)
+app.get('/redirect', (req, res) => {
+  const url = req.query.url;
+  if (url.includes('example.com')) {
+    res.redirect(url);  // Bypass: evil.com?example.com
+  }
+});
+```
+
+**Correct (allow list validation):**
+
+```typescript
+const ALLOWED_REDIRECT_HOSTS = [
+  'example.com',
+  'app.example.com',
+  'admin.example.com'
+];
+
+app.get('/redirect', (req, res) => {
+  const url = req.query.url;
+  
+  try {
+    const parsed = new URL(url);
+    
+    // Validate against allow list
+    if (!ALLOWED_REDIRECT_HOSTS.includes(parsed.hostname)) {
+      return res.status(400).json({ error: 'Invalid redirect URL' });
+    }
+    
+    res.redirect(url);
+  } catch {
+    // Invalid URL format
+    res.status(400).json({ error: 'Invalid URL format' });
+  }
+});
+
+// Or use relative URLs only
+app.get('/redirect', (req, res) => {
+  const path = req.query.path;
+  
+  // Only allow relative paths starting with /
+  if (!path.startsWith('/') || path.startsWith('//')) {
+    return res.status(400).json({ error: 'Invalid path' });
+  }
+  
+  res.redirect(path);
+});
+```
+
+**Protection strategies:**
+1. Allow list of trusted domains
+2. Use relative URLs only
+3. Validate URL structure
+4. Warning page before external redirects
+
+**Tools:** SonarQube, Semgrep, Manual Review

package/skill-assets/sunlint-code-quality/rules/typescript/S004-no-log-credentials.md

@@ -0,0 +1,71 @@
+---
+title: Do Not Log Credentials Or Tokens
+impact: MEDIUM
+impactDescription: prevents credential exposure in logs
+tags: logging, credentials, tokens, secrets, security
+---
+
+## Do Not Log Credentials Or Tokens
+
+Logs are often stored unencrypted and accessed by many people. Credentials in logs can be harvested by attackers or accidentally exposed.
+
+**Incorrect (logging sensitive data):**
+
+```typescript
+// Logging passwords
+logger.info('Login attempt', { 
+  username: user.username, 
+  password: user.password  // NEVER!
+});
+
+// Logging tokens
+logger.debug('Request headers', { headers: req.headers });
+// Authorization header contains token!
+
+// Logging full request
+logger.info('Incoming request', { body: req.body });
+// May contain password, credit card, etc.
+```
+
+**Correct (sanitized logging):**
+
+```typescript
+// Mask or omit sensitive fields
+logger.info('Login attempt', { 
+  username: user.username,
+  // password omitted
+});
+
+// Sanitize headers
+const safeHeaders = {
+  ...req.headers,
+  authorization: req.headers.authorization ? '[REDACTED]' : undefined,
+  cookie: req.headers.cookie ? '[REDACTED]' : undefined
+};
+logger.debug('Request headers', { headers: safeHeaders });
+
+// Use sanitizer for request body
+function sanitizeForLog(obj: Record<string, any>): Record<string, any> {
+  const sensitiveFields = ['password', 'token', 'secret', 'credit_card', 'ssn'];
+  const sanitized = { ...obj };
+  
+  for (const field of sensitiveFields) {
+    if (field in sanitized) {
+      sanitized[field] = '[REDACTED]';
+    }
+  }
+  
+  return sanitized;
+}
+
+logger.info('Incoming request', { body: sanitizeForLog(req.body) });
+```
+
+**Never log:**
+- Passwords (plaintext or hashed)
+- API keys and tokens
+- Credit card numbers
+- Social Security Numbers
+- Session identifiers
+
+**Tools:** SonarQube, Semgrep, Log Audit

package/skill-assets/sunlint-code-quality/rules/typescript/S005-server-authorization.md

@@ -0,0 +1,68 @@
+---
+title: Enforce Authorization At Trusted Service Layer
+impact: CRITICAL
+impactDescription: prevents client-side authorization bypass
+tags: authorization, server-side, middleware, access-control, security
+---
+
+## Enforce Authorization At Trusted Service Layer
+
+Client-side authorization can be bypassed. All permission checks must occur server-side where they cannot be manipulated.
+
+**Incorrect (client-side or trusting client data):**
+
+```typescript
+// Client-side authorization (can be bypassed)
+if (user.role === 'admin') {
+  showAdminPanel();  // Just hide/show - not secure!
+}
+
+// Trusting client-sent role
+app.delete('/users/:id', (req, res) => {
+  const userRole = req.body.role;  // From client!
+  if (userRole === 'admin') {
+    deleteUser(req.params.id);
+  }
+});
+
+// Hidden form field for authorization
+<input type="hidden" name="isAdmin" value="true" />
+```
+
+**Correct (server-side authorization):**
+
+```typescript
+// Server-side authorization
+const authMiddleware = (requiredRole: string) => {
+  return async (req: Request, res: Response, next: NextFunction) => {
+    const user = await getUserFromToken(req.headers.authorization);
+    if (!user) {
+      return res.status(401).json({ error: 'Unauthorized' });
+    }
+    
+    const hasPermission = await checkPermission(user.id, requiredRole);
+    if (!hasPermission) {
+      return res.status(403).json({ error: 'Forbidden' });
+    }
+    
+    req.user = user;
+    next();
+  };
+};
+
+app.delete('/users/:id', 
+  authMiddleware('admin'),  // Server-side check
+  async (req, res) => {
+    await deleteUser(req.params.id);
+    res.json({ success: true });
+  }
+);
+```
+
+**Never trust:**
+- Client-side JavaScript checks
+- Hidden form fields
+- URL parameters for access control
+- Unvalidated tokens from browser storage
+
+**Tools:** Manual Review, Static Analysis, Penetration Testing