0eec95323c
This commit introduces significant enhancements and refactoring to the Task Master CLI, focusing on improved testing, integration with Perplexity AI for research-backed task updates, and core logic refactoring for better maintainability and functionality.
**Testing Infrastructure Setup:**
- Implemented Jest as the primary testing framework, setting up a comprehensive testing environment.
- Added new test scripts to including , , and for streamlined testing workflows.
- Integrated necessary devDependencies for testing, such as , , , , and , to support unit, integration, and end-to-end testing.
**Dependency Updates:**
- Updated and to reflect the latest dependency versions, ensuring project stability and access to the newest features and security patches.
- Upgraded to version 0.9.16 and usage: openai [-h] [-v] [-b API_BASE] [-k API_KEY] [-p PROXY [PROXY ...]]
[-o ORGANIZATION] [-t {openai,azure}]
[--api-version API_VERSION] [--azure-endpoint AZURE_ENDPOINT]
[--azure-ad-token AZURE_AD_TOKEN] [-V]
{api,tools,migrate,grit} ...
positional arguments:
{api,tools,migrate,grit}
api Direct API calls
tools Client side tools for convenience
options:
-h, --help show this help message and exit
-v, --verbose Set verbosity.
-b, --api-base API_BASE
What API base url to use.
-k, --api-key API_KEY
What API key to use.
-p, --proxy PROXY [PROXY ...]
What proxy to use.
-o, --organization ORGANIZATION
Which organization to run as (will use your default
organization if not specified)
-t, --api-type {openai,azure}
The backend API to call, must be `openai` or `azure`
--api-version API_VERSION
The Azure API version, e.g.
'https://learn.microsoft.com/en-us/azure/ai-
services/openai/reference#rest-api-versioning'
--azure-endpoint AZURE_ENDPOINT
The Azure endpoint, e.g.
'https://endpoint.openai.azure.com'
--azure-ad-token AZURE_AD_TOKEN
A token from Azure Active Directory,
https://www.microsoft.com/en-
us/security/business/identity-access/microsoft-entra-
id
-V, --version show program's version number and exit to 4.89.0.
- Added dependency (version 2.3.0) and updated related dependencies to their latest versions.
**Perplexity AI Integration for Research-Backed Updates:**
- Introduced an option to leverage Perplexity AI for task updates, enabling research-backed enhancements to task details.
- Implemented logic to initialize a Perplexity AI client if the environment variable is available.
- Modified the function to accept a parameter, allowing dynamic selection between Perplexity AI and Claude AI for task updates based on API key availability and user preference.
- Enhanced to handle responses from Perplexity AI and update tasks accordingly, including improved error handling and logging for robust operation.
**Core Logic Refactoring and Improvements:**
- Refactored the function to utilize task IDs instead of dependency IDs, ensuring consistency and clarity in dependency management.
- Implemented a new function to rigorously check for both circular dependencies and self-dependencies within tasks, improving task relationship integrity.
- Enhanced UI elements in :
- Refactored to incorporate icons for different task statuses and utilize a object for color mapping, improving visual representation of task status.
- Updated to display colored complexity scores with emojis, providing a more intuitive and visually appealing representation of task complexity.
- Refactored the task data structure creation and validation process:
- Updated the JSON Schema for to reflect a more streamlined and efficient task structure.
- Implemented Task Model Classes for better data modeling and type safety.
- Improved File System Operations for task data management.
- Developed robust Validation Functions and an Error Handling System to ensure data integrity and application stability.
**Testing Guidelines Implementation:**
- Implemented guidelines for writing testable code when developing new features, promoting a test-driven development approach.
- Added testing requirements and best practices for unit, integration, and edge case testing to ensure comprehensive test coverage.
- Updated the development workflow to mandate writing tests before proceeding with configuration and documentation updates, reinforcing the importance of testing throughout the development lifecycle.
This commit collectively enhances the Task Master CLI's reliability, functionality, and developer experience through improved testing practices, AI-powered research capabilities, and a more robust and maintainable codebase.
152 lines
11 KiB
Plaintext
152 lines
11 KiB
Plaintext
---
|
|
description: Describes the high-level architecture of the Task Master CLI application.
|
|
globs: scripts/modules/*.js
|
|
alwaysApply: false
|
|
---
|
|
|
|
# Application Architecture Overview
|
|
|
|
- **Modular Structure**: The Task Master CLI is built using a modular architecture, with distinct modules responsible for different aspects of the application. This promotes separation of concerns, maintainability, and testability.
|
|
|
|
- **Main Modules and Responsibilities**:
|
|
|
|
- **[`commands.js`](mdc:scripts/modules/commands.js): Command Handling**
|
|
- **Purpose**: Defines and registers all CLI commands using Commander.js.
|
|
- **Responsibilities**:
|
|
- Parses command-line arguments and options.
|
|
- Invokes appropriate functions from other modules to execute commands.
|
|
- Handles user input and output related to command execution.
|
|
- Implements input validation and error handling for CLI commands.
|
|
- **Key Components**:
|
|
- `programInstance` (Commander.js `Command` instance): Manages command definitions.
|
|
- `registerCommands(programInstance)`: Function to register all application commands.
|
|
- Command action handlers: Functions executed when a specific command is invoked.
|
|
|
|
- **[`task-manager.js`](mdc:scripts/modules/task-manager.js): Task Data Management**
|
|
- **Purpose**: Manages task data, including loading, saving, creating, updating, deleting, and querying tasks.
|
|
- **Responsibilities**:
|
|
- Reads and writes task data to `tasks.json` file.
|
|
- Implements functions for task CRUD operations (Create, Read, Update, Delete).
|
|
- Handles task parsing from PRD documents using AI.
|
|
- Manages task expansion and subtask generation.
|
|
- Updates task statuses and properties.
|
|
- Implements task listing and display logic.
|
|
- Performs task complexity analysis using AI.
|
|
- **Key Functions**:
|
|
- `readTasks(tasksPath)` / `writeTasks(tasksPath, tasksData)`: Load and save task data.
|
|
- `parsePRD(prdFilePath, outputPath, numTasks)`: Parses PRD document to create tasks.
|
|
- `expandTask(taskId, numSubtasks, useResearch, prompt, force)`: Expands a task into subtasks.
|
|
- `setTaskStatus(tasksPath, taskIdInput, newStatus)`: Updates task status.
|
|
- `listTasks(tasksPath, statusFilter, withSubtasks)`: Lists tasks with filtering and subtask display options.
|
|
- `analyzeComplexity(tasksPath, reportPath, useResearch, thresholdScore)`: Analyzes task complexity.
|
|
|
|
- **[`dependency-manager.js`](mdc:scripts/modules/dependency-manager.js): Dependency Management**
|
|
- **Purpose**: Manages task dependencies, including adding, removing, validating, and fixing dependency relationships.
|
|
- **Responsibilities**:
|
|
- Adds and removes task dependencies.
|
|
- Validates dependency relationships to prevent circular dependencies and invalid references.
|
|
- Fixes invalid dependencies by removing non-existent or self-referential dependencies.
|
|
- Provides functions to check for circular dependencies.
|
|
- **Key Functions**:
|
|
- `addDependency(tasksPath, taskId, dependencyId)`: Adds a dependency between tasks.
|
|
- `removeDependency(tasksPath, taskId, dependencyId)`: Removes a dependency.
|
|
- `validateDependencies(tasksPath)`: Validates task dependencies.
|
|
- `fixDependencies(tasksPath)`: Fixes invalid task dependencies.
|
|
- `isCircularDependency(tasks, taskId, dependencyChain)`: Detects circular dependencies.
|
|
|
|
- **[`ui.js`](mdc:scripts/modules/ui.js): User Interface Components**
|
|
- **Purpose**: Handles all user interface elements, including displaying information, formatting output, and providing user feedback.
|
|
- **Responsibilities**:
|
|
- Displays task lists, task details, and command outputs in a formatted way.
|
|
- Uses `chalk` for colored output and `boxen` for boxed messages.
|
|
- Implements table display using `cli-table3`.
|
|
- Shows loading indicators using `ora`.
|
|
- Provides helper functions for status formatting, dependency display, and progress reporting.
|
|
- Suggests next actions to the user after command execution.
|
|
- **Key Functions**:
|
|
- `displayTaskList(tasks, statusFilter, withSubtasks)`: Displays a list of tasks in a table.
|
|
- `displayTaskDetails(task)`: Displays detailed information for a single task.
|
|
- `displayComplexityReport(reportPath)`: Displays the task complexity report.
|
|
- `startLoadingIndicator(message)` / `stopLoadingIndicator(indicator)`: Manages loading indicators.
|
|
- `getStatusWithColor(status)`: Returns status string with color formatting.
|
|
- `formatDependenciesWithStatus(dependencies, allTasks, inTable)`: Formats dependency list with status indicators.
|
|
|
|
- **[`ai-services.js`](mdc:scripts/modules/ai-services.js) (Conceptual): AI Integration**
|
|
- **Purpose**: Abstracts interactions with AI models (like Anthropic Claude and Perplexity AI) for various features. *Note: This module might be implicitly implemented within `task-manager.js` and `utils.js` or could be explicitly created for better organization as the project evolves.*
|
|
- **Responsibilities**:
|
|
- Handles API calls to AI services.
|
|
- Manages prompts and parameters for AI requests.
|
|
- Parses AI responses and extracts relevant information.
|
|
- Implements logic for task complexity analysis, task expansion, and PRD parsing using AI.
|
|
- **Potential Functions**:
|
|
- `getAIResponse(prompt, model, maxTokens, temperature)`: Generic function to interact with AI model.
|
|
- `analyzeTaskComplexityWithAI(taskDescription)`: Sends task description to AI for complexity analysis.
|
|
- `expandTaskWithAI(taskDescription, numSubtasks, researchContext)`: Generates subtasks using AI.
|
|
- `parsePRDWithAI(prdContent)`: Extracts tasks from PRD content using AI.
|
|
|
|
- **[`utils.js`](mdc:scripts/modules/utils.js): Utility Functions and Configuration**
|
|
- **Purpose**: Provides reusable utility functions and global configuration settings used across the application.
|
|
- **Responsibilities**:
|
|
- Manages global configuration settings loaded from environment variables and defaults.
|
|
- Implements logging utility with different log levels and output formatting.
|
|
- Provides file system operation utilities (read/write JSON files).
|
|
- Includes string manipulation utilities (e.g., `truncate`, `sanitizePrompt`).
|
|
- Offers task-specific utility functions (e.g., `formatTaskId`, `findTaskById`, `taskExists`).
|
|
- Implements graph algorithms like cycle detection for dependency management.
|
|
- **Key Components**:
|
|
- `CONFIG`: Global configuration object.
|
|
- `log(level, ...args)`: Logging function.
|
|
- `readJSON(filepath)` / `writeJSON(filepath, data)`: File I/O utilities for JSON files.
|
|
- `truncate(text, maxLength)`: String truncation utility.
|
|
- `formatTaskId(id)` / `findTaskById(tasks, taskId)`: Task ID and search utilities.
|
|
- `findCycles(subtaskId, dependencyMap)`: Cycle detection algorithm.
|
|
|
|
- **Data Flow and Module Dependencies**:
|
|
|
|
- **Commands Initiate Actions**: User commands entered via the CLI (handled by [`commands.js`](mdc:scripts/modules/commands.js)) are the entry points for most operations.
|
|
- **Command Handlers Delegate to Managers**: Command handlers in [`commands.js`](mdc:scripts/modules/commands.js) call functions in [`task-manager.js`](mdc:scripts/modules/task-manager.js) and [`dependency-manager.js`](mdc:scripts/modules/dependency-manager.js) to perform core task and dependency management logic.
|
|
- **UI for Presentation**: [`ui.js`](mdc:scripts/modules/ui.js) is used by command handlers and task/dependency managers to display information to the user. UI functions primarily consume data and format it for output, without modifying core application state.
|
|
- **Utilities for Common Tasks**: [`utils.js`](mdc:scripts/modules/utils.js) provides helper functions used by all other modules for configuration, logging, file operations, and common data manipulations.
|
|
- **AI Services Integration**: AI functionalities (complexity analysis, task expansion, PRD parsing) are invoked from [`task-manager.js`](mdc:scripts/modules/task-manager.js) and potentially [`commands.js`](mdc:scripts/modules/commands.js), likely using functions that would reside in a dedicated `ai-services.js` module or be integrated within `utils.js` or `task-manager.js`.
|
|
|
|
- **Testing Architecture**:
|
|
|
|
- **Test Organization Structure**:
|
|
- **Unit Tests**: Located in `tests/unit/`, reflect the module structure with one test file per module
|
|
- **Integration Tests**: Located in `tests/integration/`, test interactions between modules
|
|
- **End-to-End Tests**: Located in `tests/e2e/`, test complete workflows from a user perspective
|
|
- **Test Fixtures**: Located in `tests/fixtures/`, provide reusable test data
|
|
|
|
- **Module Design for Testability**:
|
|
- **Explicit Dependencies**: Functions accept their dependencies as parameters rather than using globals
|
|
- **Functional Style**: Pure functions with minimal side effects make testing deterministic
|
|
- **Separate Logic from I/O**: Core business logic is separated from file system operations
|
|
- **Clear Module Interfaces**: Each module has well-defined exports that can be mocked in tests
|
|
- **Callback Isolation**: Callbacks are defined as separate functions for easier testing
|
|
- **Stateless Design**: Modules avoid maintaining internal state where possible
|
|
|
|
- **Mock Integration Patterns**:
|
|
- **External Libraries**: Libraries like `fs`, `commander`, and `@anthropic-ai/sdk` are mocked at module level
|
|
- **Internal Modules**: Application modules are mocked with appropriate spy functions
|
|
- **Testing Function Callbacks**: Callbacks are extracted from mock call arguments and tested in isolation
|
|
- **UI Elements**: Output functions from `ui.js` are mocked to verify display calls
|
|
|
|
- **Testing Flow**:
|
|
- Module dependencies are mocked (following Jest's hoisting behavior)
|
|
- Test modules are imported after mocks are established
|
|
- Spy functions are set up on module methods
|
|
- Tests call the functions under test and verify behavior
|
|
- Mocks are reset between test cases to maintain isolation
|
|
|
|
- **Benefits of this Architecture**:
|
|
|
|
- **Maintainability**: Modules are self-contained and focused, making it easier to understand, modify, and debug specific features.
|
|
- **Testability**: Each module can be tested in isolation (unit testing), and interactions between modules can be tested (integration testing).
|
|
- **Mocking Support**: The clear dependency boundaries make mocking straightforward
|
|
- **Test Isolation**: Each component can be tested without affecting others
|
|
- **Callback Testing**: Function callbacks can be extracted and tested independently
|
|
- **Reusability**: Utility functions and UI components can be reused across different parts of the application.
|
|
- **Scalability**: New features can be added as new modules or by extending existing ones without significantly impacting other parts of the application.
|
|
- **Clarity**: The modular structure provides a clear separation of concerns, making the codebase easier to navigate and understand for developers.
|
|
|
|
This architectural overview should help AI models understand the structure and organization of the Task Master CLI codebase, enabling them to more effectively assist with code generation, modification, and understanding. |