@vibescope/mcp-server 0.3.13 → 0.3.14

package/src/handlers/tool-docs.test.ts

@@ -0,0 +1,511 @@
+import { describe, it, expect } from 'vitest';
+import { TOOL_INFO } from './tool-docs.js';
+import { TOOL_CATEGORIES } from './discovery.js';
+
+// ============================================================================
+// TOOL_INFO Structure Tests
+// ============================================================================
+
+describe('TOOL_INFO', () => {
+	it('should be a non-empty object', () => {
+		expect(TOOL_INFO).toBeDefined();
+		expect(typeof TOOL_INFO).toBe('object');
+		expect(Object.keys(TOOL_INFO).length).toBeGreaterThan(0);
+	});
+
+	it('should have at least 50 tool documentations', () => {
+		const toolCount = Object.keys(TOOL_INFO).length;
+		expect(toolCount).toBeGreaterThanOrEqual(50);
+	});
+
+	it('should only have string values', () => {
+		for (const [toolName, doc] of Object.entries(TOOL_INFO)) {
+			expect(typeof doc).toBe('string');
+			if (typeof doc !== 'string') {
+				throw new Error(`Tool ${toolName} has non-string documentation`);
+			}
+		}
+	});
+
+	it('should not have empty documentation strings', () => {
+		for (const [toolName, doc] of Object.entries(TOOL_INFO)) {
+			expect(doc.trim().length).toBeGreaterThan(0);
+			if (doc.trim().length === 0) {
+				throw new Error(`Tool ${toolName} has empty documentation`);
+			}
+		}
+	});
+});
+
+// ============================================================================
+// Documentation Format Tests
+// ============================================================================
+
+describe('Documentation format', () => {
+	it('should start with a markdown header for each tool', () => {
+		for (const [toolName, doc] of Object.entries(TOOL_INFO)) {
+			const startsWithHeader = doc.trimStart().startsWith('#');
+			expect(startsWithHeader).toBe(true);
+			if (!startsWithHeader) {
+				throw new Error(`Tool ${toolName} documentation does not start with markdown header`);
+			}
+		}
+	});
+
+	it('should contain the tool name in documentation', () => {
+		for (const [toolName, doc] of Object.entries(TOOL_INFO)) {
+			const containsToolName = doc.includes(toolName);
+			expect(containsToolName).toBe(true);
+			if (!containsToolName) {
+				throw new Error(`Tool ${toolName} documentation does not contain tool name`);
+			}
+		}
+	});
+
+	it('should have Parameters section for tools with parameters', () => {
+		// These are tools that definitely need parameters
+		const toolsWithRequiredParams = [
+			'add_task',
+			'update_task',
+			'complete_task',
+			'add_blocker',
+			'log_decision',
+			'request_deployment',
+			'create_project',
+		];
+
+		for (const toolName of toolsWithRequiredParams) {
+			const doc = TOOL_INFO[toolName];
+			if (doc) {
+				const hasParamsSection = doc.includes('**Parameters:**') || doc.includes('Parameters:');
+				expect(hasParamsSection).toBe(true);
+				if (!hasParamsSection) {
+					throw new Error(`Tool ${toolName} documentation missing Parameters section`);
+				}
+			}
+		}
+	});
+
+	it('should have reasonable documentation length (not too short)', () => {
+		const MIN_LENGTH = 50; // Minimum characters for meaningful documentation
+		for (const [toolName, doc] of Object.entries(TOOL_INFO)) {
+			expect(doc.length).toBeGreaterThanOrEqual(MIN_LENGTH);
+			if (doc.length < MIN_LENGTH) {
+				throw new Error(`Tool ${toolName} documentation is too short (${doc.length} chars)`);
+			}
+		}
+	});
+
+	it('should have reasonable documentation length (not too long)', () => {
+		const MAX_LENGTH = 5000; // Maximum to prevent token bloat
+		for (const [toolName, doc] of Object.entries(TOOL_INFO)) {
+			expect(doc.length).toBeLessThanOrEqual(MAX_LENGTH);
+			if (doc.length > MAX_LENGTH) {
+				throw new Error(`Tool ${toolName} documentation is too long (${doc.length} chars)`);
+			}
+		}
+	});
+});
+
+// ============================================================================
+// Coverage Tests - TOOL_INFO vs TOOL_CATEGORIES
+// ============================================================================
+
+describe('Tool coverage', () => {
+	it('should have documentation for all tools in TOOL_CATEGORIES', () => {
+		const missingDocs: string[] = [];
+
+		for (const [categoryName, category] of Object.entries(TOOL_CATEGORIES)) {
+			for (const tool of category.tools) {
+				if (!TOOL_INFO[tool.name]) {
+					missingDocs.push(`${tool.name} (category: ${categoryName})`);
+				}
+			}
+		}
+
+		if (missingDocs.length > 0) {
+			throw new Error(`Missing documentation for tools:\n${missingDocs.join('\n')}`);
+		}
+		expect(missingDocs.length).toBe(0);
+	});
+
+	it('should not have orphaned documentation (tools not in categories)', () => {
+		const allCategoryTools = new Set<string>();
+		for (const category of Object.values(TOOL_CATEGORIES)) {
+			for (const tool of category.tools) {
+				allCategoryTools.add(tool.name);
+			}
+		}
+
+		const orphanedDocs: string[] = [];
+		for (const toolName of Object.keys(TOOL_INFO)) {
+			if (!allCategoryTools.has(toolName)) {
+				orphanedDocs.push(toolName);
+			}
+		}
+
+		// Note: Some orphaned docs may be intentional (deprecated tools, aliases, etc.)
+		// This test warns but allows up to 10 orphaned docs
+		if (orphanedDocs.length > 10) {
+			throw new Error(`Too many orphaned documentations:\n${orphanedDocs.join('\n')}`);
+		}
+	});
+});
+
+// ============================================================================
+// Specific Tool Documentation Tests
+// ============================================================================
+
+describe('Session tool documentation', () => {
+	it('should document start_work_session', () => {
+		const doc = TOOL_INFO['start_work_session'];
+		expect(doc).toBeDefined();
+		expect(doc).toContain('session');
+		expect(doc).toContain('project');
+	});
+
+	it('should document heartbeat', () => {
+		const doc = TOOL_INFO['heartbeat'];
+		expect(doc).toBeDefined();
+		expect(doc).toContain('heartbeat');
+	});
+
+	it('should document end_work_session', () => {
+		const doc = TOOL_INFO['end_work_session'];
+		expect(doc).toBeDefined();
+		expect(doc).toContain('End');
+		expect(doc).toContain('session');
+	});
+
+	it('should document get_help', () => {
+		const doc = TOOL_INFO['get_help'];
+		expect(doc).toBeDefined();
+		expect(doc).toContain('topic');
+	});
+});
+
+describe('Task tool documentation', () => {
+	it('should document add_task with required parameters', () => {
+		const doc = TOOL_INFO['add_task'];
+		expect(doc).toBeDefined();
+		expect(doc).toContain('project_id');
+		expect(doc).toContain('title');
+	});
+
+	it('should document update_task', () => {
+		const doc = TOOL_INFO['update_task'];
+		expect(doc).toBeDefined();
+		expect(doc).toContain('task_id');
+		expect(doc).toContain('status');
+	});
+
+	it('should document complete_task', () => {
+		const doc = TOOL_INFO['complete_task'];
+		expect(doc).toBeDefined();
+		expect(doc).toContain('task_id');
+	});
+
+	it('should document get_next_task', () => {
+		const doc = TOOL_INFO['get_next_task'];
+		expect(doc).toBeDefined();
+		expect(doc).toContain('project_id');
+	});
+
+	it('should document cancel_task', () => {
+		const doc = TOOL_INFO['cancel_task'];
+		expect(doc).toBeDefined();
+		expect(doc).toContain('task_id');
+		expect(doc).toContain('cancelled_reason');
+	});
+
+	it('should document release_task', () => {
+		const doc = TOOL_INFO['release_task'];
+		expect(doc).toBeDefined();
+		expect(doc).toContain('task_id');
+	});
+
+	it('should document search_tasks with pagination info', () => {
+		const doc = TOOL_INFO['search_tasks'];
+		expect(doc).toBeDefined();
+		expect(doc).toContain('query');
+		expect(doc).toContain('limit');
+	});
+
+	it('should document batch operations', () => {
+		expect(TOOL_INFO['batch_update_tasks']).toBeDefined();
+		expect(TOOL_INFO['batch_complete_tasks']).toBeDefined();
+	});
+});
+
+describe('Deployment tool documentation', () => {
+	it('should document request_deployment', () => {
+		const doc = TOOL_INFO['request_deployment'];
+		expect(doc).toBeDefined();
+		expect(doc).toContain('project_id');
+		expect(doc).toContain('environment');
+	});
+
+	it('should document deployment lifecycle tools', () => {
+		expect(TOOL_INFO['start_deployment']).toBeDefined();
+		expect(TOOL_INFO['complete_deployment']).toBeDefined();
+		expect(TOOL_INFO['cancel_deployment']).toBeDefined();
+	});
+
+	it('should document scheduled deployments', () => {
+		expect(TOOL_INFO['schedule_deployment']).toBeDefined();
+		expect(TOOL_INFO['get_scheduled_deployments']).toBeDefined();
+		expect(TOOL_INFO['trigger_scheduled_deployment']).toBeDefined();
+	});
+
+	it('should document deployment requirements', () => {
+		expect(TOOL_INFO['add_deployment_requirement']).toBeDefined();
+		expect(TOOL_INFO['complete_deployment_requirement']).toBeDefined();
+		expect(TOOL_INFO['get_deployment_requirements']).toBeDefined();
+	});
+});
+
+describe('Validation tool documentation', () => {
+	it('should document validation workflow tools', () => {
+		expect(TOOL_INFO['get_tasks_awaiting_validation']).toBeDefined();
+		expect(TOOL_INFO['claim_validation']).toBeDefined();
+		expect(TOOL_INFO['validate_task']).toBeDefined();
+	});
+
+	it('should document claim_validation with usage hint', () => {
+		const doc = TOOL_INFO['claim_validation'];
+		expect(doc).toContain('Claim');
+		expect(doc).toContain('task');
+	});
+});
+
+describe('Blocker tool documentation', () => {
+	it('should document blocker CRUD operations', () => {
+		expect(TOOL_INFO['add_blocker']).toBeDefined();
+		expect(TOOL_INFO['resolve_blocker']).toBeDefined();
+		expect(TOOL_INFO['get_blockers']).toBeDefined();
+		expect(TOOL_INFO['delete_blocker']).toBeDefined();
+	});
+
+	it('should document add_blocker with required params', () => {
+		const doc = TOOL_INFO['add_blocker'];
+		expect(doc).toContain('project_id');
+		expect(doc).toContain('description');
+	});
+});
+
+describe('Decision tool documentation', () => {
+	it('should document decision tools', () => {
+		expect(TOOL_INFO['log_decision']).toBeDefined();
+		expect(TOOL_INFO['get_decisions']).toBeDefined();
+		expect(TOOL_INFO['delete_decision']).toBeDefined();
+	});
+
+	it('should document log_decision with title and description', () => {
+		const doc = TOOL_INFO['log_decision'];
+		expect(doc).toContain('title');
+		expect(doc).toContain('description');
+	});
+});
+
+describe('Finding tool documentation', () => {
+	it('should document finding tools', () => {
+		expect(TOOL_INFO['add_finding']).toBeDefined();
+		expect(TOOL_INFO['get_findings']).toBeDefined();
+		expect(TOOL_INFO['update_finding']).toBeDefined();
+		expect(TOOL_INFO['delete_finding']).toBeDefined();
+	});
+
+	it('should document add_finding with category and severity', () => {
+		const doc = TOOL_INFO['add_finding'];
+		expect(doc).toContain('category');
+		expect(doc).toContain('severity');
+	});
+});
+
+describe('Organization tool documentation', () => {
+	it('should document org management tools', () => {
+		expect(TOOL_INFO['create_organization']).toBeDefined();
+		expect(TOOL_INFO['update_organization']).toBeDefined();
+		expect(TOOL_INFO['delete_organization']).toBeDefined();
+	});
+
+	it('should document member management tools', () => {
+		expect(TOOL_INFO['invite_member']).toBeDefined();
+		expect(TOOL_INFO['update_member_role']).toBeDefined();
+		expect(TOOL_INFO['remove_member']).toBeDefined();
+		expect(TOOL_INFO['leave_organization']).toBeDefined();
+	});
+
+	it('should document project sharing tools', () => {
+		expect(TOOL_INFO['share_project_with_org']).toBeDefined();
+		expect(TOOL_INFO['update_project_share']).toBeDefined();
+		expect(TOOL_INFO['unshare_project']).toBeDefined();
+	});
+});
+
+describe('Bodies of Work tool documentation', () => {
+	it('should document body of work lifecycle', () => {
+		expect(TOOL_INFO['create_body_of_work']).toBeDefined();
+		expect(TOOL_INFO['update_body_of_work']).toBeDefined();
+		expect(TOOL_INFO['get_body_of_work']).toBeDefined();
+		expect(TOOL_INFO['get_bodies_of_work']).toBeDefined();
+		expect(TOOL_INFO['delete_body_of_work']).toBeDefined();
+		expect(TOOL_INFO['activate_body_of_work']).toBeDefined();
+	});
+
+	it('should document task association tools', () => {
+		expect(TOOL_INFO['add_task_to_body_of_work']).toBeDefined();
+		expect(TOOL_INFO['remove_task_from_body_of_work']).toBeDefined();
+	});
+
+	it('should document dependency management', () => {
+		expect(TOOL_INFO['add_task_dependency']).toBeDefined();
+		expect(TOOL_INFO['remove_task_dependency']).toBeDefined();
+		expect(TOOL_INFO['get_task_dependencies']).toBeDefined();
+	});
+});
+
+describe('Sprint tool documentation', () => {
+	it('should document sprint lifecycle', () => {
+		expect(TOOL_INFO['create_sprint']).toBeDefined();
+		expect(TOOL_INFO['update_sprint']).toBeDefined();
+		expect(TOOL_INFO['get_sprint']).toBeDefined();
+		expect(TOOL_INFO['get_sprints']).toBeDefined();
+		expect(TOOL_INFO['delete_sprint']).toBeDefined();
+		expect(TOOL_INFO['start_sprint']).toBeDefined();
+		expect(TOOL_INFO['complete_sprint']).toBeDefined();
+	});
+
+	it('should document sprint task management', () => {
+		expect(TOOL_INFO['add_task_to_sprint']).toBeDefined();
+		expect(TOOL_INFO['remove_task_from_sprint']).toBeDefined();
+		expect(TOOL_INFO['get_sprint_backlog']).toBeDefined();
+	});
+
+	it('should document velocity tracking', () => {
+		expect(TOOL_INFO['get_sprint_velocity']).toBeDefined();
+	});
+});
+
+describe('Discovery tool documentation', () => {
+	it('should document discover_tools', () => {
+		const doc = TOOL_INFO['discover_tools'];
+		expect(doc).toBeDefined();
+		expect(doc).toContain('category');
+	});
+
+	it('should document get_tool_info', () => {
+		const doc = TOOL_INFO['get_tool_info'];
+		expect(doc).toBeDefined();
+		expect(doc).toContain('tool_name');
+	});
+});
+
+describe('Knowledge base tool documentation', () => {
+	it('should document query_knowledge_base', () => {
+		const doc = TOOL_INFO['query_knowledge_base'];
+		expect(doc).toBeDefined();
+		expect(doc).toContain('project_id');
+		expect(doc).toContain('categories');
+	});
+});
+
+describe('Cost tool documentation', () => {
+	it('should document cost monitoring tools', () => {
+		expect(TOOL_INFO['get_cost_summary']).toBeDefined();
+		expect(TOOL_INFO['add_cost_alert']).toBeDefined();
+		expect(TOOL_INFO['update_cost_alert']).toBeDefined();
+		expect(TOOL_INFO['delete_cost_alert']).toBeDefined();
+	});
+});
+
+describe('Git issue tool documentation', () => {
+	it('should document git issue tools', () => {
+		expect(TOOL_INFO['add_git_issue']).toBeDefined();
+		expect(TOOL_INFO['resolve_git_issue']).toBeDefined();
+		expect(TOOL_INFO['get_git_issues']).toBeDefined();
+		expect(TOOL_INFO['delete_git_issue']).toBeDefined();
+	});
+
+	it('should document add_git_issue with issue types', () => {
+		const doc = TOOL_INFO['add_git_issue'];
+		expect(doc).toContain('issue_type');
+		expect(doc).toContain('branch');
+	});
+});
+
+describe('Subtask tool documentation', () => {
+	it('should document subtask tools', () => {
+		expect(TOOL_INFO['add_subtask']).toBeDefined();
+		expect(TOOL_INFO['get_subtasks']).toBeDefined();
+	});
+
+	it('should document add_subtask with parent reference', () => {
+		const doc = TOOL_INFO['add_subtask'];
+		expect(doc).toContain('parent_task_id');
+	});
+});
+
+describe('Milestone tool documentation', () => {
+	it('should document milestone tools', () => {
+		expect(TOOL_INFO['add_milestone']).toBeDefined();
+		expect(TOOL_INFO['update_milestone']).toBeDefined();
+		expect(TOOL_INFO['complete_milestone']).toBeDefined();
+		expect(TOOL_INFO['delete_milestone']).toBeDefined();
+		expect(TOOL_INFO['get_milestones']).toBeDefined();
+	});
+});
+
+describe('Idea tool documentation', () => {
+	it('should document idea tools', () => {
+		expect(TOOL_INFO['add_idea']).toBeDefined();
+		expect(TOOL_INFO['update_idea']).toBeDefined();
+		expect(TOOL_INFO['get_ideas']).toBeDefined();
+		expect(TOOL_INFO['delete_idea']).toBeDefined();
+		expect(TOOL_INFO['convert_idea_to_task']).toBeDefined();
+	});
+});
+
+describe('Fallback activity tool documentation', () => {
+	it('should document fallback tools', () => {
+		expect(TOOL_INFO['start_fallback_activity']).toBeDefined();
+		expect(TOOL_INFO['stop_fallback_activity']).toBeDefined();
+		expect(TOOL_INFO['get_activity_history']).toBeDefined();
+		expect(TOOL_INFO['get_activity_schedules']).toBeDefined();
+	});
+
+	it('should document start_fallback_activity with activity types', () => {
+		const doc = TOOL_INFO['start_fallback_activity'];
+		expect(doc).toContain('activity');
+	});
+});
+
+describe('Progress tool documentation', () => {
+	it('should document progress tools', () => {
+		expect(TOOL_INFO['log_progress']).toBeDefined();
+		expect(TOOL_INFO['get_activity_feed']).toBeDefined();
+	});
+});
+
+describe('Request handling tool documentation', () => {
+	it('should document request tools', () => {
+		expect(TOOL_INFO['get_pending_requests']).toBeDefined();
+		expect(TOOL_INFO['acknowledge_request']).toBeDefined();
+		expect(TOOL_INFO['answer_question']).toBeDefined();
+	});
+});
+
+describe('Project tool documentation', () => {
+	it('should document project tools', () => {
+		expect(TOOL_INFO['create_project']).toBeDefined();
+		expect(TOOL_INFO['update_project']).toBeDefined();
+		expect(TOOL_INFO['get_project_context']).toBeDefined();
+		expect(TOOL_INFO['update_project_readme']).toBeDefined();
+		expect(TOOL_INFO['get_git_workflow']).toBeDefined();
+	});
+
+	it('should document create_project with required fields', () => {
+		const doc = TOOL_INFO['create_project'];
+		expect(doc).toContain('name');
+	});
+});