@avisek_yorkie/cursor-rules 1.0.0

package/rules/documentation.mdc

@@ -0,0 +1,411 @@
+# Documentation Standards - JavaScript/TypeScript
+
+Good documentation is as important as good code. These standards apply to JS/TS projects.
+
+---
+
+## Core Documentation Principles
+
+### Why Document?
+- **For Future You** - You'll forget why you made decisions
+- **For Your Team** - Others need to understand your code
+- **For New Developers** - Reduce onboarding time
+- **For Users** - If you build an API or library
+
+### What to Document
+✅ **DO Document:**
+- WHY decisions were made
+- Complex algorithms and logic
+- Public APIs and interfaces
+- Setup and installation steps
+- Architecture and design decisions
+- Known limitations and gotchas
+- Examples of usage
+
+❌ **DON'T Document:**
+- Obvious code (let code self-document)
+- Implementation details that might change
+- What the code does (code shows this)
+
+### General Rules
+- Write self-documenting code as the primary documentation
+- Keep documentation close to the code it describes
+- Update documentation when code changes
+- Remove outdated or incorrect documentation
+
+---
+
+## README.md - Every Project Needs One
+
+### Essential Sections
+
+```markdown
+# Project Name
+
+Brief description of what this project does (1-2 sentences).
+
+## Table of Contents
+- [Features](#features)
+- [Installation](#installation)
+- [Usage](#usage)
+- [Configuration](#configuration)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Features
+- Feature 1
+- Feature 2
+- Feature 3
+
+## Prerequisites
+- Node.js 18+
+- (Add: database, API keys, etc.)
+
+## Installation
+
+\`\`\`bash
+git clone https://github.com/org/project.git
+cd project
+npm install
+cp .env.example .env
+# Edit .env with your configuration
+npm run dev
+\`\`\`
+
+## Usage
+
+### Basic Example
+\`\`\`javascript
+const result = doSomething();
+\`\`\`
+
+### Advanced Example
+\`\`\`javascript
+const advancedResult = doSomethingComplex({
+  option1: 'value',
+  option2: 123
+});
+\`\`\`
+
+## Configuration
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| API_URL | API endpoint | http://localhost:3000 |
+| DB_HOST | Database host | localhost |
+
+## Testing
+
+\`\`\`bash
+npm test
+npm run test:integration
+npm run test:e2e
+\`\`\`
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md)
+
+## License
+
+MIT - See [LICENSE](LICENSE)
+```
+
+### README Best Practices
+- ✅ Keep it concise but complete
+- ✅ Include code examples (JavaScript/TypeScript)
+- ✅ Update when features change
+- ✅ Add badges (build status, coverage) when applicable
+- ❌ Don't duplicate full API docs (link to them)
+- ❌ Don't include outdated information
+
+### Optional but Recommended
+- **Architecture Overview** - High-level system design
+- **Troubleshooting** - Common issues and solutions
+- **Changelog** - Link to CHANGELOG.md or version history
+- **Roadmap** - Future plans and features
+
+---
+
+## Code Comments
+
+### When to Comment
+
+```javascript
+// ✅ GOOD - Explains WHY and complex logic
+// Use exponential backoff to avoid overwhelming the API
+// during rate limit periods. Max wait time is 32 seconds.
+const backoffDelay = Math.min(Math.pow(2, retryCount) * 1000, 32000);
+
+// ✅ GOOD - Documents non-obvious behavior
+// Note: This must run before initializeDatabase() due to
+// connection pool limitations in PostgreSQL
+await setupConnectionPool();
+
+// ✅ GOOD - Explains workaround
+// HACK: Force repaint to fix Safari rendering bug
+// See: https://bugs.webkit.org/show_bug.cgi?id=123456
+element.style.display = 'none';
+element.offsetHeight; // Force reflow
+element.style.display = 'block';
+
+// ❌ BAD - States the obvious
+// Set count to zero
+const count = 0;
+
+// ❌ BAD - Redundant comment
+// Loop through users
+for (const user of users) {
+  // ...
+}
+```
+
+### TODO Comments
+
+```javascript
+// ✅ GOOD - TODO with context
+// TODO(PROJ-123): Refactor this to use new caching system
+// Current implementation has O(n²) complexity
+function slowSearch(items, query) {
+  // ...
+}
+
+// ❌ BAD - TODO without context
+// TODO: Fix this
+function doSomething() {
+  // ...
+}
+```
+
+### Comment Formatting
+- **Single-line:** `// Comment text`
+- **Multi-line:** Use `/* ... */` or multiple `//` lines; for JSDoc use `/** ... */`
+
+### Inline Comment Guidelines
+- Explain "why", not "what"
+- Document non-obvious code behavior
+- Include references to issues or external docs (e.g. MDN, GitHub issues)
+- Use TODO comments sparingly and always with context/ticket
+
+---
+
+## Function/Method Documentation (JSDoc)
+
+### Document Public APIs
+Document every public and exported function. Use JSDoc for JavaScript; TypeScript can use JSDoc or TSDoc.
+
+```javascript
+/**
+ * Calculate the total price including tax and discounts.
+ *
+ * @param {number} basePrice - The base price before tax
+ * @param {number} taxRate - Tax rate as decimal (e.g., 0.08 for 8%)
+ * @param {Object} options - Additional options
+ * @param {number} options.discount - Discount percentage (0-100)
+ * @param {string} options.currency - Currency code (default: 'USD')
+ * @returns {number} Total price after tax and discount
+ * @throws {Error} If basePrice is negative
+ *
+ * @example
+ * // Calculate price with 8% tax and 10% discount
+ * const total = calculateTotal(100, 0.08, { discount: 10 });
+ * // Returns: 97.2
+ */
+function calculateTotal(basePrice, taxRate, options = {}) {
+  if (basePrice < 0) {
+    throw new Error('Base price cannot be negative');
+  }
+
+  const { discount = 0, currency = 'USD' } = options;
+  const discountedPrice = basePrice * (1 - discount / 100);
+  return discountedPrice * (1 + taxRate);
+}
+```
+
+### With TypeScript Types
+
+```typescript
+/**
+ * Fetches a user by ID from the API.
+ *
+ * @param userId - Unique user identifier
+ * @returns The user object or null if not found
+ * @throws {ApiError} When the API request fails
+ *
+ * @example
+ * const user = await getUserById('usr_123');
+ */
+async function getUserById(userId: string): Promise<User | null> {
+  // implementation
+}
+```
+
+### Documentation Elements to Include
+- ✅ Brief description of what the function does
+- ✅ Parameters with types and descriptions
+- ✅ Return value and type
+- ✅ Exceptions/errors it might throw
+- ✅ Usage examples for non-trivial functions
+- ❌ Implementation details
+- ❌ Private helper functions (unless complex and non-obvious)
+
+### Class/Module Documentation
+- Document the purpose and responsibility of each class/module
+- Document public properties and methods with JSDoc
+- Include usage examples for complex classes
+- Document dependencies and requirements (e.g. peer dependencies)
+
+---
+
+## API Documentation
+
+### REST Endpoints
+Document each endpoint with:
+- HTTP method and path
+- Request parameters (query, path, body)
+- Request body schema (e.g. JSON)
+- Response schema and status codes
+- Authentication/authorization requirements
+- Example requests and responses
+- Error responses and status codes
+
+### Tools and Standards
+- Use **OpenAPI (Swagger)** for REST APIs
+- Keep API documentation in sync with code (generate from code or keep specs in version control)
+- Include versioning (e.g. `/v1/users`) and document in README or dedicated API doc
+
+---
+
+## Architecture Documentation
+
+### ADR (Architecture Decision Records)
+Document significant decisions in `/docs/adr/` (e.g. `001-postgres-as-primary-db.md`):
+
+```markdown
+# ADR-001: Use PostgreSQL for Primary Database
+
+## Status
+Accepted
+
+## Context
+We need a reliable database for storing user data, transactions,
+and analytics. Key requirements:
+- ACID compliance
+- Complex query support
+- Horizontal scalability
+- Strong community support
+
+## Decision
+Use PostgreSQL as our primary database.
+
+## Consequences
+
+### Positive
+- Strong ACID guarantees
+- Excellent JSON support for flexible schemas
+- Mature ecosystem and tooling
+- Great performance for complex queries
+
+### Negative
+- More complex to scale horizontally than MongoDB
+- Requires schema migrations
+- Steeper learning curve than simpler databases
+
+## Alternatives Considered
+- MongoDB: Too flexible, less data integrity
+- MySQL: Weaker JSON support, less feature-rich
+- DynamoDB: Vendor lock-in, complex pricing
+```
+
+### System Architecture Diagrams
+Use ASCII or link to diagrams (Mermaid, draw.io, etc.) in markdown:
+
+```markdown
+## System Architecture
+
+\`\`\`
+┌─────────────┐      ┌──────────────┐      ┌──────────────┐
+│   Client    │─────▶│ API Gateway  │─────▶│   Auth Svc   │
+└─────────────┘      └──────────────┘      └──────────────┘
+                             │
+                             ▼
+                      ┌──────────────┐
+                      │   User Svc    │
+                      └──────────────┘
+                             │
+                             ▼
+                      ┌──────────────┐
+                      │  PostgreSQL  │
+                      └──────────────┘
+\`\`\`
+```
+
+### What to Document
+- System architecture and design decisions
+- Component interactions and data flow
+- Deployment architecture
+- Technology choices and trade-offs
+
+---
+
+## Change Documentation
+
+- Document breaking changes prominently (README, CHANGELOG, release notes)
+- Maintain a **CHANGELOG.md** (e.g. Keep a Changelog format)
+- Use **semantic versioning** (MAJOR.MINOR.PATCH)
+- Document migration guides for major changes
+- Include deprecation notices with timelines and alternatives
+
+---
+
+## Code Examples in Documentation
+
+- Include working JavaScript/TypeScript examples
+- Keep examples simple and focused
+- Show common use cases and optional configuration
+- Include error handling where relevant
+- Ensure examples run (e.g. via tests or manual verification)
+
+---
+
+## Documentation Maintenance
+
+- Review documentation during code reviews
+- Update documentation as part of the development process
+- Remove outdated documentation
+- Keep documentation in version control
+- Use tools (e.g. TypeDoc, ESLint JSDoc rules) to check completeness
+
+---
+
+## Documentation Tools (JS/TS)
+
+- **JSDoc** - Inline API docs for JavaScript
+- **TypeDoc** - Generate docs from TypeScript
+- **API docs** - OpenAPI/Swagger for REST APIs
+- **Storybook** - Component documentation for UI libraries (React, Vue, etc.)
+
+---
+
+## Documentation Review Checklist
+
+- [ ] All public APIs and exported functions are documented (JSDoc)
+- [ ] README is complete and up-to-date
+- [ ] Code examples are correct and use JS/TS
+- [ ] Installation and prerequisites are accurate
+- [ ] API documentation matches implementation
+- [ ] Breaking changes and CHANGELOG are updated
+- [ ] No outdated or incorrect information
+- [ ] Architecture/ADR docs exist for major decisions
+
+---
+
+## Documentation Best Practices
+
+- Write for your audience (developers, users, contributors)
+- Use clear, concise language
+- Include diagrams where helpful
+- Keep documentation organized and navigable (e.g. Table of Contents)
+- Use consistent formatting and style
+- Link related documentation
+- Keep documentation in the repo and up to date

package/rules/naming-conventions.mdc

@@ -0,0 +1,291 @@
+# Naming Conventions
+
+## General Naming Principles
+
+### 1. Core Principles
+- Use descriptive names that reveal intent
+- Avoid abbreviations unless they are widely understood
+- Use consistent naming patterns throughout the codebase
+- Prefer longer, clearer names over short, cryptic ones
+- Use names from the problem domain
+- Avoid misleading names
+
+### 2. Variable Naming
+
+#### General Rules:
+- Use nouns or noun phrases for variables
+- Be specific, not generic (avoid `data`, `info`, `temp`, `value`)
+- Use singular for single items, plural for collections
+- Use meaningful prefixes/suffixes when helpful
+
+#### Good Examples:
+```javascript
+const userEmail = "user@example.com";
+const activeUsers = [];
+const isAuthenticated = true;
+const maxRetryAttempts = 3;
+const customerOrderTotal = 100.50;
+```
+
+#### Bad Examples:
+```javascript
+const data = "user@example.com";
+const arr = [];
+const flag = true;
+const num = 3;
+const temp = 100.50;
+```
+
+### 3. Function/Method Naming
+
+#### General Rules:
+- Use verbs or verb phrases for functions
+- Start with action words: `get`, `set`, `create`, `delete`, `update`, `calculate`, `validate`, `is`, `has`, `can`
+- Be specific about what the function does
+- Use consistent verb prefixes for similar operations
+
+#### Good Examples:
+```javascript
+function getUserById(id) { }
+function calculateTotalPrice(items) { }
+function isValidEmail(email) { }
+function hasPermission(user, permission) { }
+function createUserAccount(userData) { }
+function deleteExpiredSessions() { }
+```
+
+#### Bad Examples:
+```javascript
+function process(data) { }
+function doStuff() { }
+function check(x) { }
+function handle() { }
+function run() { }
+```
+
+### 4. Class/Type Naming
+
+#### General Rules:
+- Use nouns or noun phrases
+- Use PascalCase for class names
+- Be specific and descriptive
+- Avoid generic names like `Manager`, `Handler`, `Processor`
+
+#### Good Examples:
+```javascript
+class UserAccount { }
+class EmailValidator { }
+class PaymentProcessor { }
+class DatabaseConnection { }
+class OrderService { }
+```
+
+#### Bad Examples:
+```javascript
+class Manager { }
+class Handler { }
+class Processor { }
+class Helper { }
+class Utils { }
+```
+
+### 5. Constant Naming
+
+#### General Rules:
+- Use UPPER_SNAKE_CASE for constants
+- Use descriptive names that explain the value
+- Group related constants together
+- Use constants for magic numbers and strings
+
+#### Good Examples:
+```javascript
+const MAX_RETRY_ATTEMPTS = 3;
+const DEFAULT_TIMEOUT_MS = 5000;
+const API_BASE_URL = "https://api.example.com";
+const SUPPORTED_FILE_TYPES = ["jpg", "png", "gif"];
+```
+
+#### Bad Examples:
+```javascript
+const max = 3;
+const timeout = 5000;
+const url = "https://api.example.com";
+const types = ["jpg", "png", "gif"];
+```
+
+### 6. Boolean Naming
+
+#### General Rules:
+- Use prefixes: `is`, `has`, `can`, `should`, `will`, `did`
+- Use positive boolean names (avoid `isNot`, `hasNo`)
+- Be specific about what the boolean represents
+
+#### Good Examples:
+```javascript
+const isAuthenticated = true;
+const hasPermission = false;
+const canEdit = true;
+const shouldRetry = false;
+const isEmpty = true;
+const isActive = false;
+```
+
+#### Bad Examples:
+```javascript
+const authenticated = true; // unclear if it's a boolean
+const permission = false;
+const edit = true;
+const notEmpty = false; // use positive names
+const flag = true;
+```
+
+### 7. File and Directory Naming
+
+#### General Rules:
+- Use kebab-case for file and directory names
+- Use descriptive names that indicate content
+- Match file names to their primary export (if applicable)
+- Use consistent naming patterns across the project
+
+#### Good Examples:
+```
+user-service.ts
+email-validator.js
+payment-processor.ts
+user-account.component.tsx
+api-client.ts
+```
+
+#### Bad Examples:
+```
+service.ts
+validator.js
+processor.ts
+component.tsx
+```
+
+### 8. TypeScript/JavaScript Conventions
+
+- **Variables/Functions**: camelCase
+- **Classes/Interfaces/Types**: PascalCase
+- **Constants**: UPPER_SNAKE_CASE
+- **Files**: kebab-case
+- **Private members**: prefix with underscore `_privateMethod()`
+
+```typescript
+const userName = "John";
+function getUserData() { }
+class UserService { }
+const MAX_RETRIES = 3;
+interface UserAccount { }
+```
+
+### 9. Database Naming
+
+#### Tables:
+- Use plural nouns: `users`, `orders`, `products`
+- Use snake_case: `user_accounts`, `order_items`
+
+#### Columns:
+- Use snake_case: `user_id`, `created_at`, `email_address`
+- Use descriptive names: `first_name` not `fname`
+- Use consistent suffixes: `_id` for foreign keys, `_at` for timestamps
+
+#### Indexes:
+- Use descriptive names: `idx_users_email`, `idx_orders_user_id`
+
+### 10. API Naming
+
+#### REST Endpoints:
+- Use nouns, not verbs: `/users` not `/getUsers`
+- Use plural nouns: `/users` not `/user`
+- Use kebab-case or camelCase consistently
+- Use nested resources: `/users/123/orders`
+- Use query parameters for filtering: `/users?status=active`
+
+#### Good Examples:
+```
+GET /users
+GET /users/123
+POST /users
+PUT /users/123
+DELETE /users/123
+GET /users/123/orders
+GET /users?status=active&limit=10
+```
+
+#### Bad Examples:
+```
+GET /getUsers
+GET /user
+POST /createUser
+GET /userOrders/123
+GET /users?Status=Active
+```
+
+### 11. Configuration Naming
+
+#### Environment Variables:
+- Use UPPER_SNAKE_CASE
+- Use descriptive prefixes: `DB_`, `API_`, `APP_`
+- Be specific about the purpose
+
+#### Good Examples:
+```
+DATABASE_URL
+API_KEY
+APP_ENVIRONMENT
+MAX_CONNECTION_POOL_SIZE
+REDIS_HOST
+```
+
+#### Bad Examples:
+```
+db_url
+apiKey
+env
+max
+redis
+```
+
+### 12. Test Naming
+
+#### Test Functions:
+- Use descriptive names that explain what is being tested
+- Follow pattern: `test_<what>_<condition>_<expected_result>` or `should_<expected_behavior>_when_<condition>`
+
+#### Good Examples:
+```javascript
+test("should return user when valid id is provided")
+test("should throw error when email is invalid")
+test("should calculate total price correctly with tax")
+```
+
+#### Bad Examples:
+```javascript
+test("user test")
+test("test1")
+test("function works")
+```
+
+### 13. Naming Anti-Patterns to Avoid
+
+- **Single letter variables**: Only acceptable in loops (`i`, `j`, `k`) or mathematical contexts
+- **Abbreviations**: Avoid unless universally understood (`id`, `url`, `api`)
+- **Generic names**: `data`, `info`, `temp`, `value`, `obj`, `arr`
+- **Misleading names**: Names that don't match what they do
+- **Hungarian notation**: Avoid type prefixes (`strName`, `intCount`)
+- **Inconsistent casing**: Mixing camelCase and snake_case in the same context
+- **Names that differ only by case**: `user` vs `User` in the same scope
+
+### 14. Naming Review Checklist
+- [ ] Names are descriptive and reveal intent
+- [ ] No abbreviations unless widely understood
+- [ ] Consistent naming patterns throughout
+- [ ] Boolean names use appropriate prefixes (`is`, `has`, `can`)
+- [ ] Function names use action verbs
+- [ ] Class names are nouns
+- [ ] Constants are in UPPER_CASE
+- [ ] File names match their content
+- [ ] No misleading or confusing names
+- [ ] Names follow TypeScript/JavaScript conventions