Cursor rule

1---
2description: Guidelines for implementing utility functions
3globs: scripts/modules/utils.js
4alwaysApply: false
5---
6 
7# Utility Function Guidelines
8 
9## General Principles
10 
11- **Function Scope**:
12  - ✅ DO: Create utility functions that serve multiple modules
13  - ✅ DO: Keep functions single-purpose and focused
14  - ❌ DON'T: Include business logic in utility functions
15  - ❌ DON'T: Create utilities with side effects
16 
17```javascript
18  // ✅ DO: Create focused, reusable utilities
19  /**
20   * Truncates text to a specified length
21   * @param {string} text - The text to truncate
22   * @param {number} maxLength - The maximum length
23   * @returns {string} The truncated text
24   */
25  function truncate(text, maxLength) {
26    if (!text || text.length <= maxLength) {
27      return text;
28    }
29    return text.slice(0, maxLength - 3) + '...';
30  }
31```
32 
33```javascript
34  // ❌ DON'T: Add side effects to utilities
35  function truncate(text, maxLength) {
36    if (!text || text.length <= maxLength) {
37      return text;
38    }
39    
40    // Side effect - modifying global state or logging
41    console.log(`Truncating text from ${text.length} to ${maxLength} chars`);
42    
43    return text.slice(0, maxLength - 3) + '...';
44  }
45```
46 
47## Documentation Standards
48 
49- **JSDoc Format**:
50  - ✅ DO: Document all parameters and return values
51  - ✅ DO: Include descriptions for complex logic
52  - ✅ DO: Add examples for non-obvious usage
53  - ❌ DON'T: Skip documentation for "simple" functions
54 
55```javascript
56  // ✅ DO: Provide complete JSDoc documentation
57  /**
58   * Reads and parses a JSON file
59   * @param {string} filepath - Path to the JSON file
60   * @returns {Object|null} Parsed JSON data or null if error occurs
61   */
62  function readJSON(filepath) {
63    try {
64      const rawData = fs.readFileSync(filepath, 'utf8');
65      return JSON.parse(rawData);
66    } catch (error) {
67      log('error', `Error reading JSON file ${filepath}:`, error.message);
68      if (CONFIG.debug) {
69        console.error(error);
70      }
71      return null;
72    }
73  }
74```
75 
76## Configuration Management
77 
78- **Environment Variables**:
79  - ✅ DO: Provide default values for all configuration
80  - ✅ DO: Use environment variables for customization
81  - ✅ DO: Document available configuration options
82  - ❌ DON'T: Hardcode values that should be configurable
83 
84```javascript
85  // ✅ DO: Set up configuration with defaults and environment overrides
86  const CONFIG = {
87    model: process.env.MODEL || 'claude-3-7-sonnet-20250219',
88    maxTokens: parseInt(process.env.MAX_TOKENS || '4000'),
89    temperature: parseFloat(process.env.TEMPERATURE || '0.7'),
90    debug: process.env.DEBUG === "true",
91    logLevel: process.env.LOG_LEVEL || "info",
92    defaultSubtasks: parseInt(process.env.DEFAULT_SUBTASKS || "3"),
93    defaultPriority: process.env.DEFAULT_PRIORITY || "medium",
94    projectName: process.env.PROJECT_NAME || "Task Master",
95    projectVersion: "1.5.0" // Version should be hardcoded
96  };
97```
98 
99## Logging Utilities
100 
101- **Log Levels**:
102  - ✅ DO: Support multiple log levels (debug, info, warn, error)
103  - ✅ DO: Use appropriate icons for different log levels
104  - ✅ DO: Respect the configured log level
105  - ❌ DON'T: Add direct console.log calls outside the logging utility
106 
107```javascript
108  // ✅ DO: Implement a proper logging utility
109  const LOG_LEVELS = {
110    debug: 0,
111    info: 1,
112    warn: 2,
113    error: 3
114  };
115  
116  function log(level, ...args) {
117    const icons = {
118      debug: chalk.gray('🔍'),
119      info: chalk.blue('ℹ️'),
120      warn: chalk.yellow('⚠️'),
121      error: chalk.red('❌'),
122      success: chalk.green('✅')
123    };
124    
125    if (LOG_LEVELS[level] >= LOG_LEVELS[CONFIG.logLevel]) {
126      const icon = icons[level] || '';
127      console.log(`${icon} ${args.join(' ')}`);
128    }
129  }
130```
131 
132## File Operations
133 
134- **Error Handling**:
135  - ✅ DO: Use try/catch blocks for all file operations
136  - ✅ DO: Return null or a default value on failure
137  - ✅ DO: Log detailed error information
138  - ❌ DON'T: Allow exceptions to propagate unhandled
139 
140```javascript
141  // ✅ DO: Handle file operation errors properly
142  function writeJSON(filepath, data) {
143    try {
144      fs.writeFileSync(filepath, JSON.stringify(data, null, 2));
145    } catch (error) {
146      log('error', `Error writing JSON file ${filepath}:`, error.message);
147      if (CONFIG.debug) {
148        console.error(error);
149      }
150    }
151  }
152```
153 
154## Task-Specific Utilities
155 
156- **Task ID Formatting**:
157  - ✅ DO: Create utilities for consistent ID handling
158  - ✅ DO: Support different ID formats (numeric, string, dot notation)
159  - ❌ DON'T: Duplicate formatting logic across modules
160 
161```javascript
162  // ✅ DO: Create utilities for common operations
163  /**
164   * Formats a task ID as a string
165   * @param {string|number} id - The task ID to format
166   * @returns {string} The formatted task ID
167   */
168  function formatTaskId(id) {
169    if (typeof id === 'string' && id.includes('.')) {
170      return id; // Already formatted as a string with a dot (e.g., "1.2")
171    }
172    
173    if (typeof id === 'number') {
174      return id.toString();
175    }
176    
177    return id;
178  }
179```
180 
181- **Task Search**:
182  - ✅ DO: Implement reusable task finding utilities
183  - ✅ DO: Support both task and subtask lookups
184  - ✅ DO: Add context to subtask results
185 
186```javascript
187  // ✅ DO: Create comprehensive search utilities
188  /**
189   * Finds a task by ID in the tasks array
190   * @param {Array} tasks - The tasks array
191   * @param {string|number} taskId - The task ID to find
192   * @returns {Object|null} The task object or null if not found
193   */
194  function findTaskById(tasks, taskId) {
195    if (!taskId || !tasks || !Array.isArray(tasks)) {
196      return null;
197    }
198    
199    // Check if it's a subtask ID (e.g., "1.2")
200    if (typeof taskId === 'string' && taskId.includes('.')) {
201      const [parentId, subtaskId] = taskId.split('.').map(id => parseInt(id, 10));
202      const parentTask = tasks.find(t => t.id === parentId);
203      
204      if (!parentTask || !parentTask.subtasks) {
205        return null;
206      }
207      
208      const subtask = parentTask.subtasks.find(st => st.id === subtaskId);
209      if (subtask) {
210        // Add reference to parent task for context
211        subtask.parentTask = { 
212          id: parentTask.id, 
213          title: parentTask.title,
214          status: parentTask.status
215        };
216        subtask.isSubtask = true;
217      }
218      
219      return subtask || null;
220    }
221    
222    const id = parseInt(taskId, 10);
223    return tasks.find(t => t.id === id) || null;
224  }
225```
226 
227## Cycle Detection
228 
229- **Graph Algorithms**:
230  - ✅ DO: Implement cycle detection using graph traversal
231  - ✅ DO: Track visited nodes and recursion stack
232  - ✅ DO: Return specific information about cycles
233 
234```javascript
235  // ✅ DO: Implement proper cycle detection
236  /**
237   * Find cycles in a dependency graph using DFS
238   * @param {string} subtaskId - Current subtask ID
239   * @param {Map} dependencyMap - Map of subtask IDs to their dependencies
240   * @param {Set} visited - Set of visited nodes
241   * @param {Set} recursionStack - Set of nodes in current recursion stack
242   * @returns {Array} - List of dependency edges that need to be removed to break cycles
243   */
244  function findCycles(subtaskId, dependencyMap, visited = new Set(), recursionStack = new Set(), path = []) {
245    // Mark the current node as visited and part of recursion stack
246    visited.add(subtaskId);
247    recursionStack.add(subtaskId);
248    path.push(subtaskId);
249    
250    const cyclesToBreak = [];
251    
252    // Get all dependencies of the current subtask
253    const dependencies = dependencyMap.get(subtaskId) || [];
254    
255    // For each dependency
256    for (const depId of dependencies) {
257      // If not visited, recursively check for cycles
258      if (!visited.has(depId)) {
259        const cycles = findCycles(depId, dependencyMap, visited, recursionStack, [...path]);
260        cyclesToBreak.push(...cycles);
261      } 
262      // If the dependency is in the recursion stack, we found a cycle
263      else if (recursionStack.has(depId)) {
264        // The last edge in the cycle is what we want to remove
265        cyclesToBreak.push(depId);
266      }
267    }
268    
269    // Remove the node from recursion stack before returning
270    recursionStack.delete(subtaskId);
271    
272    return cyclesToBreak;
273  }
274```
275 
276## Export Organization
277 
278- **Grouping Related Functions**:
279  - ✅ DO: Export all utility functions in a single statement
280  - ✅ DO: Group related exports together
281  - ✅ DO: Export configuration constants
282  - ❌ DON'T: Use default exports
283 
284```javascript
285  // ✅ DO: Organize exports logically
286  export {
287    // Configuration
288    CONFIG,
289    LOG_LEVELS,
290    
291    // Logging
292    log,
293    
294    // File operations
295    readJSON,
296    writeJSON,
297    
298    // String manipulation
299    sanitizePrompt,
300    truncate,
301    
302    // Task utilities
303    readComplexityReport,
304    findTaskInComplexityReport,
305    taskExists,
306    formatTaskId,
307    findTaskById,
308    
309    // Graph algorithms
310    findCycles,
311  };
312```
313 
314Refer to [`utils.js`](mdc:scripts/modules/utils.js) for implementation examples and [`new_features.mdc`](mdc:.cursor/rules/new_features.mdc) for integration guidelines.