@goonnguyen/human-mcp 1.2.0 → 1.3.0

package/plans/004-fix-typescript-compilation-errors-plan.md

@@ -0,0 +1,388 @@
+# Plan 004: Fix TypeScript Compilation Errors in CI/CD Pipeline
+
+## Executive Summary
+
+This plan addresses critical TypeScript compilation errors that are causing the CI/CD pipeline to fail. The main issues are:
+1. Type assertions on `unknown` types in test files (18046 errors)
+2. Incorrect import statement for type-only imports when `verbatimModuleSyntax` is enabled (1484 error)
+
+These errors prevent the test suite from running and block the release pipeline.
+
+## Problem Analysis
+
+### 1. Root Causes Identified
+
+#### A. Unknown Type Assertions (TS18046)
+- **Location**: Multiple test files (sse-transport.test.ts, test-server-manager.ts)
+- **Problem**: Variables of type `unknown` are being accessed without proper type guards
+- **Impact**: TypeScript compilation fails with error TS18046
+- **Evidence**: 
+  ```
+  tests/integration/sse-transport.test.ts(41,14): error TS18046: 'health' is of type 'unknown'.
+  tests/integration/sse-transport.test.ts(78,14): error TS18046: 'error' is of type 'unknown'.
+  ```
+
+#### B. Incorrect Type Import (TS1484)
+- **Location**: tests/unit/formatters.test.ts
+- **Problem**: `AnalysisOptions` is imported as a value when it should be a type-only import
+- **Impact**: Violates `verbatimModuleSyntax` TypeScript setting
+- **Evidence**:
+  ```
+  tests/unit/formatters.test.ts(3,10): error TS1484: 'AnalysisOptions' is a type and must be imported using a type-only import
+  ```
+
+### 2. Secondary Issues
+
+- CI/CD pipeline blocks on TypeScript errors before tests can run
+- No type safety in test assertions
+- Missing proper type definitions for API responses
+
+## Technical Solution
+
+### 1. Fix Type-Only Import in Formatters Test
+
+#### File: `tests/unit/formatters.test.ts`
+
+**Current Code (Line 3):**
+```typescript
+import { AnalysisOptions } from "../../src/types/index.js";
+```
+
+**Fixed Code:**
+```typescript
+import type { AnalysisOptions } from "../../src/types/index.js";
+```
+
+**Rationale**: When `verbatimModuleSyntax` is enabled in tsconfig.json, TypeScript requires explicit `type` imports for type-only symbols.
+
+### 2. Fix Unknown Type Assertions in SSE Transport Tests
+
+#### File: `tests/integration/sse-transport.test.ts`
+
+**Lines 36-48 - Health Check Test:**
+
+**Current Code:**
+```typescript
+it("should include SSE fallback status in health check", async () => {
+  const response = await fetch(`${baseUrl}/health`);
+  const health = await response.json();
+  
+  expect(health.status).toBe("healthy");
+  expect(health.transport).toBe("streamable-http");
+  expect(health.sseFallback).toBe("enabled");
+  expect(health.ssePaths).toEqual({
+    stream: "/sse",
+    message: "/messages"
+  });
+});
+```
+
+**Fixed Code:**
+```typescript
+it("should include SSE fallback status in health check", async () => {
+  const response = await fetch(`${baseUrl}/health`);
+  const health = await response.json() as {
+    status: string;
+    transport: string;
+    sseFallback: string;
+    ssePaths: {
+      stream: string;
+      message: string;
+    };
+  };
+  
+  expect(health.status).toBe("healthy");
+  expect(health.transport).toBe("streamable-http");
+  expect(health.sseFallback).toBe("enabled");
+  expect(health.ssePaths).toEqual({
+    stream: "/sse",
+    message: "/messages"
+  });
+});
+```
+
+**Lines 73-79 - Error Response Test:**
+
+**Current Code:**
+```typescript
+expect(response.status).toBe(400);
+const error = await response.json();
+expect(error.error.message).toContain("Missing sessionId");
+```
+
+**Fixed Code:**
+```typescript
+expect(response.status).toBe(400);
+const error = await response.json() as { error: { message: string } };
+expect(error.error.message).toContain("Missing sessionId");
+```
+
+**Lines 93-97 - Invalid Session Test:**
+
+**Current Code:**
+```typescript
+expect(response.status).toBe(400);
+const error = await response.json();
+expect(error.error.message).toContain("No active SSE session");
+```
+
+**Fixed Code:**
+```typescript
+expect(response.status).toBe(400);
+const error = await response.json() as { error: { message: string } };
+expect(error.error.message).toContain("No active SSE session");
+```
+
+**Lines 135-139 - Transport Mixing Test:**
+
+**Current Code:**
+```typescript
+expect(response.status).toBe(400);
+const error = await response.json();
+expect(error.error.message).toContain("streamable HTTP transport");
+```
+
+**Fixed Code:**
+```typescript
+expect(response.status).toBe(400);
+const error = await response.json() as { error: { message: string } };
+expect(error.error.message).toContain("streamable HTTP transport");
+```
+
+### 3. Fix Unknown Type Assertions in Test Server Manager
+
+#### File: `tests/utils/test-server-manager.ts`
+
+**Lines 113-117 - Server Ready Check:**
+
+**Current Code:**
+```typescript
+if (response.ok) {
+  const health = await response.json();
+  if (health.status === 'healthy') {
+    return;
+  }
+}
+```
+
+**Fixed Code:**
+```typescript
+if (response.ok) {
+  const health = await response.json() as { status: string };
+  if (health.status === 'healthy') {
+    return;
+  }
+}
+```
+
+### 4. Create Type Definitions for Test Responses
+
+To improve type safety and avoid inline type assertions, create proper type definitions:
+
+#### New File: `tests/types/api-responses.ts`
+
+```typescript
+// Type definitions for API responses used in tests
+
+export interface HealthCheckResponse {
+  status: 'healthy' | 'unhealthy';
+  transport: string;
+  sseFallback?: string;
+  ssePaths?: {
+    stream: string;
+    message: string;
+  };
+  version?: string;
+  timestamp?: number;
+}
+
+export interface ErrorResponse {
+  error: {
+    code?: string;
+    message: string;
+    details?: any;
+  };
+}
+
+export interface MCPResponse {
+  jsonrpc: '2.0';
+  id?: number | string;
+  result?: any;
+  error?: {
+    code: number;
+    message: string;
+    data?: any;
+  };
+}
+
+export interface SessionResponse {
+  sessionId: string;
+  createdAt: number;
+  expiresAt?: number;
+}
+```
+
+### 5. Update Tests to Use Type Definitions
+
+#### Updated File: `tests/integration/sse-transport.test.ts`
+
+Add import at the top:
+```typescript
+import type { HealthCheckResponse, ErrorResponse } from "../types/api-responses.js";
+```
+
+Update test assertions:
+```typescript
+it("should include SSE fallback status in health check", async () => {
+  const response = await fetch(`${baseUrl}/health`);
+  const health = await response.json() as HealthCheckResponse;
+  
+  expect(health.status).toBe("healthy");
+  expect(health.transport).toBe("streamable-http");
+  expect(health.sseFallback).toBe("enabled");
+  expect(health.ssePaths).toEqual({
+    stream: "/sse",
+    message: "/messages"
+  });
+});
+```
+
+#### Updated File: `tests/utils/test-server-manager.ts`
+
+Add import at the top:
+```typescript
+import type { HealthCheckResponse } from "../types/api-responses.js";
+```
+
+Update server ready check:
+```typescript
+if (response.ok) {
+  const health = await response.json() as HealthCheckResponse;
+  if (health.status === 'healthy') {
+    return;
+  }
+}
+```
+
+## Implementation Steps
+
+### Phase 1: Immediate Fixes (Priority: CRITICAL)
+1. **Fix type-only import in formatters.test.ts**
+   - Add `type` keyword to AnalysisOptions import
+   - Verify no other type-only imports are missing
+
+2. **Fix unknown type assertions in test files**
+   - Add type assertions to all `response.json()` calls
+   - Ensure proper typing for all test assertions
+
+### Phase 2: Type Safety Improvements (Priority: HIGH)
+3. **Create type definitions file**
+   - Define interfaces for all API responses
+   - Export types for use across test files
+
+4. **Update all test files to use type definitions**
+   - Import response types
+   - Replace inline type assertions with defined types
+
+### Phase 3: Validation (Priority: HIGH)
+5. **Run TypeScript compilation locally**
+   - Execute `bun run typecheck`
+   - Verify no compilation errors
+
+6. **Run test suite**
+   - Execute `bun test`
+   - Ensure all tests pass with proper types
+
+## Testing Strategy
+
+### Local Validation
+```bash
+# Check TypeScript compilation
+bun run typecheck
+
+# Run unit tests
+bun test tests/unit/
+
+# Run integration tests  
+bun test tests/integration/
+
+# Run all tests
+bun test
+```
+
+### CI/CD Validation
+- Push changes to trigger GitHub Actions
+- Verify TypeScript compilation passes
+- Confirm all tests execute successfully
+- Check that release pipeline completes
+
+## Risk Mitigation
+
+### Risks and Mitigations
+
+1. **Risk**: Type assertions might hide runtime errors
+   - **Mitigation**: Use proper type guards where possible, validate API responses
+
+2. **Risk**: Breaking existing test functionality
+   - **Mitigation**: Only add type information, don't change test logic
+
+3. **Risk**: Future TypeScript updates might introduce new errors
+   - **Mitigation**: Pin TypeScript version, document type requirements
+
+## Success Criteria
+
+- [ ] TypeScript compilation passes without errors
+- [ ] All unit tests pass
+- [ ] All integration tests pass
+- [ ] CI/CD pipeline completes successfully
+- [ ] No runtime type errors in tests
+
+## Timeline
+
+- **Immediate**: Fix compilation errors (30 minutes)
+- **Short-term**: Add type definitions (1 hour)
+- **Validation**: Test and verify (30 minutes)
+
+## TODO Checklist
+
+### Immediate Actions
+- [ ] Fix type-only import in `tests/unit/formatters.test.ts`
+- [ ] Add type assertions in `tests/integration/sse-transport.test.ts`
+- [ ] Add type assertion in `tests/utils/test-server-manager.ts`
+
+### Type Safety Improvements
+- [ ] Create `tests/types/api-responses.ts`
+- [ ] Update test files to use type definitions
+- [ ] Add JSDoc comments for complex types
+
+### Validation
+- [ ] Run `bun run typecheck` locally
+- [ ] Run full test suite
+- [ ] Verify CI/CD pipeline passes
+
+## Files to Modify
+
+1. `tests/unit/formatters.test.ts` - Fix type-only import
+2. `tests/integration/sse-transport.test.ts` - Add type assertions
+3. `tests/utils/test-server-manager.ts` - Add type assertion
+4. `tests/types/api-responses.ts` - Create new file with type definitions
+
+## Dependencies
+
+- No new package dependencies required
+- Uses existing TypeScript configuration
+- Leverages Bun's built-in TypeScript support
+
+## Notes
+
+- The `verbatimModuleSyntax` setting in tsconfig.json enforces stricter import/export syntax
+- Type assertions should be used judiciously and replaced with proper type guards where possible
+- Consider adding runtime validation for API responses in production code
+- Future improvement: Add JSON schema validation for API responses
+
+## References
+
+- [TypeScript verbatimModuleSyntax](https://www.typescriptlang.org/tsconfig#verbatimModuleSyntax)
+- [TypeScript Type Assertions](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#type-assertions)
+- [TypeScript Unknown Type](https://www.typescriptlang.org/docs/handbook/2/functions.html#unknown)
+- [Bun TypeScript Support](https://bun.sh/docs/runtime/typescript)