@bryan-thompson/inspector-assessment-cli 1.35.3 → 1.36.1

package/build/__tests__/assess-full-e2e.test.js

@@ -14,7 +14,7 @@
  *
  * @see https://github.com/triepod-ai/inspector-assessment/issues/97
  */
-import { describe, it, expect, beforeAll, afterAll } from "@jest/globals";
+import { jest, describe, it, expect, beforeAll, afterAll, afterEach, } from "@jest/globals";
 import { spawn } from "child_process";
 import * as fs from "fs";
 import * as path from "path";
@@ -76,6 +76,10 @@ async function spawnCLI(args, timeout = 60000) {
         // Set timeout
         const timer = setTimeout(() => {
             if (proc && !proc.killed) {
+                // Destroy streams before killing to prevent memory leaks
+                proc.stdout?.destroy();
+                proc.stderr?.destroy();
+                proc.stdin?.destroy();
                 proc.kill("SIGTERM");
                 exitCode = -1; // Indicate timeout
             }
@@ -83,6 +87,10 @@ async function spawnCLI(args, timeout = 60000) {
         // Handle process exit
         proc.on("close", (code) => {
             clearTimeout(timer);
+            // Destroy streams to prevent memory leaks
+            proc?.stdout?.destroy();
+            proc?.stderr?.destroy();
+            proc?.stdin?.destroy();
             // Don't overwrite timeout exit code (-1)
             if (exitCode !== -1) {
                 exitCode = code;
@@ -100,6 +108,10 @@ async function spawnCLI(args, timeout = 60000) {
         // Handle errors
         proc.on("error", (err) => {
             clearTimeout(timer);
+            // Destroy streams to prevent memory leaks
+            proc?.stdout?.destroy();
+            proc?.stderr?.destroy();
+            proc?.stdin?.destroy();
             stderr += `\nProcess error: ${err.message}`;
             resolve({
                 stdout,
@@ -151,10 +163,10 @@ function parseJSONLEvents(stderr) {
  * @returns True if server responds, false otherwise
  */
 async function checkServerAvailable(url) {
+    const controller = new AbortController();
+    // Give enough time to receive initial response but not wait forever
+    const timeoutId = setTimeout(() => controller.abort(), 5000);
     try {
-        const controller = new AbortController();
-        // Give enough time to receive initial response but not wait forever
-        const timeoutId = setTimeout(() => controller.abort(), 5000);
         const response = await fetch(url, {
             method: "POST",
             headers: DEFAULT_HEADERS,
@@ -172,26 +184,22 @@ async function checkServerAvailable(url) {
         });
         // Server responded with a status code - check if it's OK
         if (response.status >= 500) {
-            clearTimeout(timeoutId);
             return false;
         }
         // For SSE responses, check if we can read any data
         // This confirms the server is actually responding
         const reader = response.body?.getReader();
         if (!reader) {
-            clearTimeout(timeoutId);
             return response.status < 500;
         }
         try {
             // Try to read the first chunk
             const { done, value } = await reader.read();
-            clearTimeout(timeoutId);
             reader.cancel(); // Cancel the stream - we don't need more data
             // If we got any data, the server is available
             return !done && value && value.length > 0;
         }
         catch {
-            clearTimeout(timeoutId);
             // If read fails after successful fetch, server still responded
             return true;
         }
@@ -199,6 +207,11 @@ async function checkServerAvailable(url) {
     catch {
         return false;
     }
+    finally {
+        // Always clean up timeout and abort controller
+        clearTimeout(timeoutId);
+        controller.abort();
+    }
 }
 /**
  * Create a temporary config file for testing
@@ -235,9 +248,19 @@ function createInvalidConfig(content, filename) {
     return configPath;
 }
 // ============================================================================
+// E2E Skip Check
+// ============================================================================
+/**
+ * Skip E2E tests unless RUN_E2E_TESTS is set.
+ * This prevents long timeouts when testbed servers aren't running.
+ *
+ * To run E2E tests: RUN_E2E_TESTS=1 npm test -- --testPathPattern="e2e"
+ */
+const describeE2E = process.env.RUN_E2E_TESTS ? describe : describe.skip;
+// ============================================================================
 // Test Setup
 // ============================================================================
-describe("CLI E2E Integration Tests", () => {
+describeE2E("CLI E2E Integration Tests", () => {
     afterEach(() => {
         jest.clearAllMocks();
     });

package/build/__tests__/assess-full.test.js

@@ -6,7 +6,7 @@
  * external dependencies. For integration testing of the full CLI, use the
  * actual CLI binary.
  */
-import { describe, it, expect } from "@jest/globals";
+import { jest, describe, it, expect, afterEach } from "@jest/globals";
 import * as path from "path";
 /**
  * Pure function tests - these test logic concepts used in the CLI

package/build/__tests__/assessment-runner/assessment-executor.test.js

@@ -3,7 +3,7 @@
  *
  * Tests for runFullAssessment() orchestration logic.
  */
-import { jest, describe, it, expect, beforeEach, afterEach, } from "@jest/globals";
+import { jest, describe, it, expect, beforeEach, afterEach, afterAll, } from "@jest/globals";
 // Mock all dependencies with explicit any types for flexibility
 const mockLoadServerConfig = jest.fn();
 const mockConnectToServer = jest.fn();
@@ -137,6 +137,19 @@ describe("runFullAssessment", () => {
     afterEach(() => {
         jest.restoreAllMocks();
     });
+    afterAll(() => {
+        // Clean up module mocks to prevent memory leaks
+        jest.unmock("../../lib/assessment-runner/server-config.js");
+        jest.unmock("../../lib/assessment-runner/server-connection.js");
+        jest.unmock("../../lib/assessment-runner/source-loader.js");
+        jest.unmock("../../lib/assessment-runner/tool-wrapper.js");
+        jest.unmock("../../lib/assessment-runner/config-builder.js");
+        jest.unmock("../../../../client/lib/services/assessment/AssessmentOrchestrator.js");
+        jest.unmock("../../assessmentState.js");
+        jest.unmock("../../lib/jsonl-events.js");
+        jest.unmock("fs");
+        jest.unmock("../../../../client/lib/lib/assessmentTypes.js");
+    });
     describe("orchestration flow", () => {
         it("should load server config", async () => {
             await runFullAssessment(defaultOptions);
@@ -203,7 +216,7 @@ describe("runFullAssessment", () => {
                 ...defaultOptions,
                 sourceCodePath: "/path/to/source",
             });
-            expect(mockLoadSourceFiles).toHaveBeenCalledWith("/path/to/source");
+            expect(mockLoadSourceFiles).toHaveBeenCalledWith("/path/to/source", undefined);
         });
         it("should not load source files when path does not exist", async () => {
             const fs = await import("fs");

package/build/__tests__/assessment-runner/config-builder.test.js

@@ -62,6 +62,12 @@ describe("buildConfig", () => {
     afterEach(() => {
         process.env = originalEnv;
     });
+    afterAll(() => {
+        jest.unmock("../../profiles.js");
+        jest.unmock("../../../../client/lib/lib/assessmentTypes.js");
+        jest.unmock("../../../../client/lib/services/assessment/lib/claudeCodeBridge.js");
+        jest.unmock("../../../../client/lib/services/assessment/config/performanceConfig.js");
+    });
     describe("default configuration", () => {
         it("should spread DEFAULT_ASSESSMENT_CONFIG", () => {
             const result = buildConfig({ serverName: "test" });

package/build/__tests__/assessment-runner/index.test.js

@@ -3,7 +3,7 @@
  *
  * Tests for the facade module exports.
  */
-import { describe, it, expect } from "@jest/globals";
+import { jest, describe, it, expect, afterEach } from "@jest/globals";
 // Import the barrel/facade module
 import * as assessmentRunner from "../../lib/assessment-runner/index.js";
 describe("assessment-runner index exports", () => {
@@ -11,24 +11,26 @@ describe("assessment-runner index exports", () => {
         jest.clearAllMocks();
     });
     describe("function exports", () => {
-        it("should export all 6 public functions", () => {
+        it("should export all 7 public functions", () => {
             expect(typeof assessmentRunner.loadServerConfig).toBe("function");
             expect(typeof assessmentRunner.loadSourceFiles).toBe("function");
+            expect(typeof assessmentRunner.resolveSourcePath).toBe("function");
             expect(typeof assessmentRunner.connectToServer).toBe("function");
             expect(typeof assessmentRunner.createCallToolWrapper).toBe("function");
             expect(typeof assessmentRunner.buildConfig).toBe("function");
             expect(typeof assessmentRunner.runFullAssessment).toBe("function");
         });
-        it("should export exactly 6 functions", () => {
+        it("should export exactly 7 functions", () => {
             const functionNames = Object.keys(assessmentRunner).filter((key) => typeof assessmentRunner[key] ===
                 "function");
-            expect(functionNames).toHaveLength(6);
+            expect(functionNames).toHaveLength(7);
             expect(functionNames.sort()).toEqual([
                 "buildConfig",
                 "connectToServer",
                 "createCallToolWrapper",
                 "loadServerConfig",
                 "loadSourceFiles",
+                "resolveSourcePath",
                 "runFullAssessment",
             ]);
         });

package/build/__tests__/assessment-runner/path-resolver.test.js

@@ -0,0 +1,112 @@
+/**
+ * Path Resolver Unit Tests
+ *
+ * Tests for resolveSourcePath() that handles path normalization.
+ */
+import { jest, describe, it, expect, beforeEach, afterAll, } from "@jest/globals";
+import * as path from "path";
+import * as os from "os";
+// Mock fs module
+jest.unstable_mockModule("fs", () => ({
+    existsSync: jest.fn(),
+    realpathSync: jest.fn(),
+}));
+// Import after mocking
+const fs = await import("fs");
+const { resolveSourcePath } = await import("../../lib/assessment-runner/path-resolver.js");
+describe("resolveSourcePath", () => {
+    const mockExistsSync = fs.existsSync;
+    const mockRealpathSync = fs.realpathSync;
+    beforeEach(() => {
+        mockExistsSync.mockReturnValue(false);
+        mockRealpathSync.mockReturnValue("");
+    });
+    afterEach(() => {
+        jest.clearAllMocks();
+    });
+    afterAll(() => {
+        jest.unmock("fs");
+    });
+    describe("tilde expansion", () => {
+        it("should expand ~ to home directory", () => {
+            mockExistsSync.mockReturnValue(false);
+            const result = resolveSourcePath("~/project");
+            expect(result).toBe(path.join(os.homedir(), "project"));
+        });
+        it("should expand ~/subdir/path correctly", () => {
+            mockExistsSync.mockReturnValue(false);
+            const result = resolveSourcePath("~/foo/bar/baz");
+            expect(result).toBe(path.join(os.homedir(), "foo/bar/baz"));
+        });
+        it("should not modify paths without tilde", () => {
+            mockExistsSync.mockReturnValue(false);
+            const result = resolveSourcePath("/absolute/path");
+            expect(result).toBe("/absolute/path");
+        });
+    });
+    describe("relative path resolution", () => {
+        it("should resolve relative paths to absolute", () => {
+            mockExistsSync.mockReturnValue(false);
+            const cwd = process.cwd();
+            const result = resolveSourcePath("./src");
+            expect(result).toBe(path.resolve(cwd, "./src"));
+        });
+        it("should resolve parent directory references", () => {
+            mockExistsSync.mockReturnValue(false);
+            const cwd = process.cwd();
+            const result = resolveSourcePath("../sibling");
+            expect(result).toBe(path.resolve(cwd, "../sibling"));
+        });
+        it("should handle bare directory names", () => {
+            mockExistsSync.mockReturnValue(false);
+            const cwd = process.cwd();
+            const result = resolveSourcePath("mydir");
+            expect(result).toBe(path.resolve(cwd, "mydir"));
+        });
+    });
+    describe("symlink resolution", () => {
+        it("should follow symlinks when path exists", () => {
+            const symlinkPath = "/tmp/symlink";
+            const realPath = "/actual/target/path";
+            mockExistsSync.mockImplementation((p) => p === symlinkPath);
+            mockRealpathSync.mockReturnValue(realPath);
+            const result = resolveSourcePath(symlinkPath);
+            expect(mockRealpathSync).toHaveBeenCalledWith(symlinkPath);
+            expect(result).toBe(realPath);
+        });
+        it("should not call realpathSync when path does not exist", () => {
+            mockExistsSync.mockReturnValue(false);
+            resolveSourcePath("/nonexistent/path");
+            expect(mockRealpathSync).not.toHaveBeenCalled();
+        });
+        it("should handle broken symlinks gracefully", () => {
+            const brokenSymlink = "/tmp/broken-symlink";
+            mockExistsSync.mockReturnValue(true);
+            mockRealpathSync.mockImplementation(() => {
+                throw new Error("ENOENT: no such file or directory");
+            });
+            // Should not throw, should return the resolved path without realpath
+            const result = resolveSourcePath(brokenSymlink);
+            expect(result).toBe(brokenSymlink);
+        });
+    });
+    describe("combined scenarios", () => {
+        it("should handle ~ with symlink resolution", () => {
+            const tildePathExpanded = path.join(os.homedir(), "project");
+            const realPath = "/real/project/path";
+            mockExistsSync.mockImplementation((p) => p === tildePathExpanded);
+            mockRealpathSync.mockReturnValue(realPath);
+            const result = resolveSourcePath("~/project");
+            expect(result).toBe(realPath);
+        });
+        it("should handle relative path with symlink resolution", () => {
+            const cwd = process.cwd();
+            const resolvedRelative = path.resolve(cwd, "./src");
+            const realPath = "/real/src/path";
+            mockExistsSync.mockImplementation((p) => p === resolvedRelative);
+            mockRealpathSync.mockReturnValue(realPath);
+            const result = resolveSourcePath("./src");
+            expect(result).toBe(realPath);
+        });
+    });
+});

package/build/__tests__/assessment-runner/server-config.test.js

@@ -22,6 +22,9 @@ describe("loadServerConfig", () => {
         jest.clearAllMocks();
         mockExistsSync.mockReturnValue(false);
     });
+    afterAll(() => {
+        jest.unmock("fs");
+    });
     describe("config path resolution", () => {
         it("should search explicit configPath first when provided", () => {
             const configPath = "/custom/path/config.json";

package/build/__tests__/assessment-runner/server-connection.test.js

@@ -45,6 +45,12 @@ describe("connectToServer", () => {
     afterEach(() => {
         jest.clearAllMocks();
     });
+    afterAll(() => {
+        jest.unmock("@modelcontextprotocol/sdk/client/index.js");
+        jest.unmock("@modelcontextprotocol/sdk/client/stdio.js");
+        jest.unmock("@modelcontextprotocol/sdk/client/sse.js");
+        jest.unmock("@modelcontextprotocol/sdk/client/streamableHttp.js");
+    });
     describe("HTTP transport", () => {
         it("should create StreamableHTTPClientTransport for transport:http", async () => {
             const config = {

package/build/__tests__/assessment-runner/source-loader.test.js

@@ -40,6 +40,9 @@ describe("loadSourceFiles", () => {
     afterEach(() => {
         jest.clearAllMocks();
     });
+    afterAll(() => {
+        jest.unmock("fs");
+    });
     describe("README discovery", () => {
         it("should find README.md in source directory", () => {
             const sourcePath = "/project";
@@ -77,6 +80,98 @@ describe("loadSourceFiles", () => {
             const result = loadSourceFiles(sourcePath);
             expect(result.readmeContent).toBeUndefined();
         });
+        // Issue #151: Extended README patterns
+        it("should find README.markdown", () => {
+            const sourcePath = "/project";
+            mockExistsSync.mockImplementation((p) => p === path.join(sourcePath, "README.markdown"));
+            mockReadFileSync.mockReturnValue("# Markdown README");
+            const result = loadSourceFiles(sourcePath);
+            expect(result.readmeContent).toBe("# Markdown README");
+        });
+        it("should find README.txt", () => {
+            const sourcePath = "/project";
+            mockExistsSync.mockImplementation((p) => p === path.join(sourcePath, "README.txt"));
+            mockReadFileSync.mockReturnValue("Text README content");
+            const result = loadSourceFiles(sourcePath);
+            expect(result.readmeContent).toBe("Text README content");
+        });
+        it("should find README without extension", () => {
+            const sourcePath = "/project";
+            mockExistsSync.mockImplementation((p) => p === path.join(sourcePath, "README"));
+            mockReadFileSync.mockReturnValue("No extension README");
+            const result = loadSourceFiles(sourcePath);
+            expect(result.readmeContent).toBe("No extension README");
+        });
+        it("should prioritize README.md over other variants", () => {
+            const sourcePath = "/project";
+            // Multiple README files exist - README.md should be found first
+            mockExistsSync.mockImplementation((p) => {
+                return (p === path.join(sourcePath, "README.md") ||
+                    p === path.join(sourcePath, "README.txt") ||
+                    p === path.join(sourcePath, "README"));
+            });
+            mockReadFileSync.mockImplementation((p) => {
+                if (p.endsWith("README.md"))
+                    return "# MD README";
+                if (p.endsWith("README.txt"))
+                    return "TXT README";
+                if (p.endsWith("README"))
+                    return "Plain README";
+                return "";
+            });
+            const result = loadSourceFiles(sourcePath);
+            expect(result.readmeContent).toBe("# MD README");
+        });
+    });
+    describe("debug logging", () => {
+        it("should log debug output when debug flag is true", () => {
+            const sourcePath = "/project";
+            const consoleSpy = jest
+                .spyOn(console, "log")
+                .mockImplementation(() => { });
+            try {
+                mockExistsSync.mockReturnValue(false);
+                mockReaddirSync.mockReturnValue([]);
+                loadSourceFiles(sourcePath, true);
+                // Verify debug logging was called
+                expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining("[source-loader]"));
+            }
+            finally {
+                consoleSpy.mockRestore();
+            }
+        });
+        it("should not log debug output when debug flag is false", () => {
+            const sourcePath = "/project";
+            const consoleSpy = jest
+                .spyOn(console, "log")
+                .mockImplementation(() => { });
+            try {
+                mockExistsSync.mockReturnValue(false);
+                mockReaddirSync.mockReturnValue([]);
+                loadSourceFiles(sourcePath, false);
+                // Verify debug logging was NOT called
+                expect(consoleSpy).not.toHaveBeenCalledWith(expect.stringContaining("[source-loader]"));
+            }
+            finally {
+                consoleSpy.mockRestore();
+            }
+        });
+        it("should not log debug output by default", () => {
+            const sourcePath = "/project";
+            const consoleSpy = jest
+                .spyOn(console, "log")
+                .mockImplementation(() => { });
+            try {
+                mockExistsSync.mockReturnValue(false);
+                mockReaddirSync.mockReturnValue([]);
+                loadSourceFiles(sourcePath);
+                // Verify debug logging was NOT called by default
+                expect(consoleSpy).not.toHaveBeenCalledWith(expect.stringContaining("[source-loader]"));
+            }
+            finally {
+                consoleSpy.mockRestore();
+            }
+        });
     });
     describe("package.json parsing", () => {
         it("should parse package.json when present", () => {
@@ -120,13 +215,17 @@ describe("loadSourceFiles", () => {
             const consoleSpy = jest
                 .spyOn(console, "warn")
                 .mockImplementation(() => { });
-            mockExistsSync.mockImplementation((p) => p === path.join(sourcePath, "manifest.json"));
-            mockReadFileSync.mockReturnValue("{ invalid json }");
-            const result = loadSourceFiles(sourcePath);
-            expect(result.manifestRaw).toBe("{ invalid json }");
-            expect(result.manifestJson).toBeUndefined();
-            expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining("Failed to parse manifest.json"));
-            consoleSpy.mockRestore();
+            try {
+                mockExistsSync.mockImplementation((p) => p === path.join(sourcePath, "manifest.json"));
+                mockReadFileSync.mockReturnValue("{ invalid json }");
+                const result = loadSourceFiles(sourcePath);
+                expect(result.manifestRaw).toBe("{ invalid json }");
+                expect(result.manifestJson).toBeUndefined();
+                expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining("Failed to parse manifest.json"));
+            }
+            finally {
+                consoleSpy.mockRestore();
+            }
         });
     });
     describe("source file collection", () => {
@@ -278,14 +377,18 @@ describe("loadSourceFiles", () => {
             const consoleSpy = jest
                 .spyOn(console, "warn")
                 .mockImplementation(() => { });
-            mockExistsSync.mockReturnValue(false);
-            mockReaddirSync.mockImplementation(() => {
-                throw new Error("Permission denied");
-            });
-            const result = loadSourceFiles(sourcePath);
-            expect(result.sourceCodeFiles?.size).toBe(0);
-            expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining("Could not load source files"), expect.any(Error));
-            consoleSpy.mockRestore();
+            try {
+                mockExistsSync.mockReturnValue(false);
+                mockReaddirSync.mockImplementation(() => {
+                    throw new Error("Permission denied");
+                });
+                const result = loadSourceFiles(sourcePath);
+                expect(result.sourceCodeFiles?.size).toBe(0);
+                expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining("Could not load source files"), expect.any(Error));
+            }
+            finally {
+                consoleSpy.mockRestore();
+            }
         });
         it("should skip unreadable files silently", () => {
             const sourcePath = "/project";

package/build/__tests__/assessment-runner-facade.test.js

@@ -6,7 +6,7 @@
  *
  * @see https://github.com/triepod-ai/inspector-assessment/issues/96
  */
-import { describe, it, expect } from "@jest/globals";
+import { jest, describe, it, expect, afterEach } from "@jest/globals";
 // Test named imports (the primary consumer pattern)
 import { loadServerConfig, loadSourceFiles, connectToServer, createCallToolWrapper, buildConfig, runFullAssessment, } from "../lib/assessment-runner.js";
 // Test namespace import
@@ -84,13 +84,14 @@ describe("Assessment Runner Facade", () => {
     describe("Export Completeness", () => {
         it("should export exactly 6 functions", () => {
             const exportedFunctions = Object.entries(AssessmentRunner).filter(([, value]) => typeof value === "function");
-            expect(exportedFunctions.length).toBe(6);
+            expect(exportedFunctions.length).toBe(7);
             expect(exportedFunctions.map(([name]) => name).sort()).toEqual([
                 "buildConfig",
                 "connectToServer",
                 "createCallToolWrapper",
                 "loadServerConfig",
                 "loadSourceFiles",
+                "resolveSourcePath",
                 "runFullAssessment",
             ]);
         });
@@ -99,6 +100,7 @@ describe("Assessment Runner Facade", () => {
             const expectedExports = [
                 "loadServerConfig",
                 "loadSourceFiles",
+                "resolveSourcePath",
                 "connectToServer",
                 "createCallToolWrapper",
                 "buildConfig",

package/build/__tests__/cli-build-fixes.test.js

@@ -8,7 +8,7 @@
  * @see https://github.com/triepod-ai/inspector-assessment/issues/33
  * @see https://github.com/triepod-ai/inspector-assessment/issues/37
  */
-import { describe, it, expect } from "@jest/globals";
+import { jest, describe, it, expect, afterEach } from "@jest/globals";
 import { ScopedListenerConfig } from "../lib/event-config.js";
 describe("CLI Build Fixes Regression Tests", () => {
     afterEach(() => {

package/build/__tests__/flag-parsing.test.js

@@ -669,8 +669,9 @@ describe("parseArgs Zod Schema Integration", () => {
         // Run any pending timers and restore
         jest.runAllTimers();
         jest.useRealTimers();
-        processExitSpy.mockRestore();
-        consoleErrorSpy.mockRestore();
+        // Use optional chaining in case spies weren't created (prevents memory leaks)
+        processExitSpy?.mockRestore();
+        consoleErrorSpy?.mockRestore();
     });
     describe("LogLevelSchema integration", () => {
         it("parseArgs validates log level with LogLevelSchema", () => {

package/build/__tests__/http-transport-integration.test.js

@@ -7,8 +7,15 @@
  *
  * Note: Tests skip gracefully when testbed servers are unavailable.
  */
-import { describe, it, expect, beforeAll } from "@jest/globals";
+import { jest, describe, it, expect, beforeAll, afterEach, } from "@jest/globals";
+/**
+ * Skip integration tests unless RUN_E2E_TESTS is set.
+ * This prevents long timeouts when testbed servers aren't running.
+ *
+ * To run: RUN_E2E_TESTS=1 npm test -- --testPathPattern="http-transport-integration"
+ */
 import { createTransport } from "../transport.js";
+const describeE2E = process.env.RUN_E2E_TESTS ? describe : describe.skip;
 // Testbed server URLs
 const VULNERABLE_MCP_URL = "http://localhost:10900/mcp";
 const HARDENED_MCP_URL = "http://localhost:10901/mcp";
@@ -24,9 +31,9 @@ const DEFAULT_HEADERS = {
  * Check if a server is available by sending a basic HTTP request
  */
 async function checkServerAvailable(url) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 5000);
     try {
-        const controller = new AbortController();
-        const timeoutId = setTimeout(() => controller.abort(), 5000);
         const response = await fetch(url, {
             method: "POST",
             headers: DEFAULT_HEADERS,
@@ -42,13 +49,17 @@ async function checkServerAvailable(url) {
             }),
             signal: controller.signal,
         });
-        clearTimeout(timeoutId);
         // Accept any response (200 or error) as indication server is up
         return response.status < 500;
     }
     catch {
         return false;
     }
+    finally {
+        // Always clean up timeout and abort controller to prevent memory leaks
+        clearTimeout(timeoutId);
+        controller.abort();
+    }
 }
 /**
  * Parse SSE response to extract JSON data
@@ -100,7 +111,7 @@ async function sendMcpRequest(url, method, params = {}, headers = {}) {
     }
     return { response, data };
 }
-describe("HTTP Transport Integration", () => {
+describeE2E("HTTP Transport Integration", () => {
     afterEach(() => {
         jest.clearAllMocks();
     });

package/build/__tests__/jsonl-events.test.js

@@ -40,7 +40,7 @@ describe("JSONL Event Emission", () => {
         });
         it("should include schemaVersion field", () => {
             emitJSONL({ event: "test" });
-            expect(emittedEvents[0]).toHaveProperty("schemaVersion", 1);
+            expect(emittedEvents[0]).toHaveProperty("schemaVersion", 3);
         });
         it("should handle complex nested objects", () => {
             emitJSONL({

package/build/__tests__/profiles.test.js

@@ -127,17 +127,25 @@ describe("resolveModuleNames", () => {
     });
     it("should emit warnings for deprecated modules when warn=true", () => {
         const consoleSpy = jest.spyOn(console, "warn").mockImplementation(() => { });
-        const modules = ["documentation"];
-        resolveModuleNames(modules, true);
-        expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining("deprecated"));
-        consoleSpy.mockRestore();
+        try {
+            const modules = ["documentation"];
+            resolveModuleNames(modules, true);
+            expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining("deprecated"));
+        }
+        finally {
+            consoleSpy.mockRestore();
+        }
     });
     it("should not emit warnings when warn=false", () => {
         const consoleSpy = jest.spyOn(console, "warn").mockImplementation(() => { });
-        const modules = ["documentation"];
-        resolveModuleNames(modules, false);
-        expect(consoleSpy).not.toHaveBeenCalled();
-        consoleSpy.mockRestore();
+        try {
+            const modules = ["documentation"];
+            resolveModuleNames(modules, false);
+            expect(consoleSpy).not.toHaveBeenCalled();
+        }
+        finally {
+            consoleSpy.mockRestore();
+        }
     });
 });
 describe("getProfileModules", () => {

package/build/__tests__/security/security-pattern-count.test.js

@@ -13,7 +13,7 @@
  * CLI tools override this to 30 patterns for comprehensive security assessment.
  * This test verifies consistency within each context.
  */
-import { describe, it, expect } from "@jest/globals";
+import { jest, describe, it, expect, afterEach } from "@jest/globals";
 import * as fs from "fs";
 import * as path from "path";
 import { fileURLToPath } from "url";
@@ -134,9 +134,9 @@ describe("Security Pattern Count Consistency", () => {
             // Default: "default all 8" or "default 8"
             expect(content).toMatch(/securityPatternsToTest\?\s*:\s*number;.*default.*8/i);
             // Reviewer mode: "Test only 3 critical"
-            expect(content).toMatch(/securityPatternsToTest:\s*3;.*3 critical/i);
+            expect(content).toMatch(/securityPatternsToTest:\s*3,.*3 critical/i);
             // Developer/audit modes: "all security patterns" or "all 8"
-            expect(content).toMatch(/securityPatternsToTest:\s*8;.*all.*8|8.*patterns/i);
+            expect(content).toMatch(/securityPatternsToTest:\s*8,.*all.*8|8.*patterns/i);
         });
         it("should document pattern count in help text comments", () => {
             const filePath = path.join(projectRoot, "cli/src/assess-security.ts");

package/build/__tests__/stage3-fix-validation.test.js

@@ -6,7 +6,7 @@
  *
  * @see https://github.com/triepod-ai/inspector-assessment/issues/137
  */
-import { describe, it, expect } from "@jest/globals";
+import { jest, describe, it, expect, afterEach } from "@jest/globals";
 import { AssessmentOptionsSchema, safeParseAssessmentOptions, validateAssessmentOptions, } from "../lib/cli-parserSchemas.js";
 describe("Stage 3 Fix Validation Tests", () => {
     afterEach(() => {

package/build/__tests__/testbed-integration.test.js

@@ -11,7 +11,14 @@
  *
  * Note: Tests skip gracefully when testbed servers are unavailable.
  */
-import { describe, it, expect, beforeAll } from "@jest/globals";
+import { jest, describe, it, expect, beforeAll, afterEach, } from "@jest/globals";
+/**
+ * Skip integration tests unless RUN_E2E_TESTS is set.
+ * This prevents long timeouts when testbed servers aren't running.
+ *
+ * To run: RUN_E2E_TESTS=1 npm test -- --testPathPattern="testbed-integration"
+ */
+const describeE2E = process.env.RUN_E2E_TESTS ? describe : describe.skip;
 // Testbed server URLs
 const VULNERABLE_URL = "http://localhost:10900/mcp";
 const HARDENED_URL = "http://localhost:10901/mcp";
@@ -26,9 +33,9 @@ const DEFAULT_HEADERS = {
  * Check if a server is available by sending an initialize request
  */
 async function checkServerAvailable(url) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 5000);
     try {
-        const controller = new AbortController();
-        const timeoutId = setTimeout(() => controller.abort(), 5000);
         const response = await fetch(url, {
             method: "POST",
             headers: DEFAULT_HEADERS,
@@ -44,12 +51,16 @@ async function checkServerAvailable(url) {
             }),
             signal: controller.signal,
         });
-        clearTimeout(timeoutId);
         return response.status < 500;
     }
     catch {
         return false;
     }
+    finally {
+        // Always clean up timeout and abort controller to prevent memory leaks
+        clearTimeout(timeoutId);
+        controller.abort();
+    }
 }
 /**
  * Parse SSE response to extract JSON data
@@ -119,7 +130,7 @@ async function callTool(url, toolName, args) {
     });
     return data;
 }
-describe("Testbed A/B Comparison", () => {
+describeE2E("Testbed A/B Comparison", () => {
     afterEach(() => {
         jest.clearAllMocks();
     });

package/build/__tests__/transport.test.js

@@ -5,7 +5,7 @@
  * Tests focus on input validation and error handling rather than
  * mocked transport implementations due to ESM limitations.
  */
-import { describe, it, expect } from "@jest/globals";
+import { jest, describe, it, expect, afterEach } from "@jest/globals";
 import { createTransport } from "../transport.js";
 describe("Transport Creation", () => {
     afterEach(() => {

package/build/lib/__tests__/cli-parserSchemas.test.js

@@ -5,7 +5,7 @@
  *
  * @module cli/lib/__tests__/cli-parserSchemas
  */
-// Uses Jest globals (describe, test, expect)
+import { jest, describe, test, expect, afterEach } from "@jest/globals";
 import { ZodError } from "zod";
 import { AssessmentProfileNameSchema, AssessmentModuleNameSchema, ServerConfigSchema, AssessmentOptionsSchema, ValidationResultSchema, validateAssessmentOptions, validateServerConfig, parseAssessmentOptions, safeParseAssessmentOptions, parseModuleNames, safeParseModuleNames, LogLevelSchema, ReportFormatSchema, TransportTypeSchema, ZOD_SCHEMA_VERSION, } from "../cli-parserSchemas.js";
 describe("cli-parserSchemas", () => {

package/build/lib/assessment-runner/__tests__/server-configSchemas.test.js

@@ -5,7 +5,7 @@
  *
  * @module cli/lib/assessment-runner/__tests__/server-configSchemas
  */
-// Uses Jest globals (describe, test, expect)
+import { jest, describe, test, expect, afterEach } from "@jest/globals";
 import { ZodError } from "zod";
 import { HttpSseServerConfigSchema, StdioServerConfigSchema, ServerEntrySchema, ClaudeDesktopConfigSchema, StandaloneConfigSchema, ConfigFileSchema, parseConfigFile, safeParseConfigFile, validateServerEntry, isHttpSseConfig, isStdioConfig, TransportTypeSchema, } from "../server-configSchemas.js";
 describe("server-configSchemas", () => {

package/build/lib/assessment-runner/assessment-executor.js

@@ -12,9 +12,12 @@ import { AssessmentStateManager } from "../../assessmentState.js";
 import { emitServerConnected, emitToolDiscovered, emitToolsDiscoveryComplete, emitAssessmentComplete, emitTestBatch, emitVulnerabilityFound, emitAnnotationMissing, emitAnnotationMisaligned, emitAnnotationReviewRecommended, emitAnnotationAligned, emitModulesConfigured, emitPhaseStarted, emitPhaseComplete, emitToolTestComplete, emitValidationSummary, } from "../jsonl-events.js";
 import { loadServerConfig } from "./server-config.js";
 import { loadSourceFiles } from "./source-loader.js";
+import { resolveSourcePath } from "./path-resolver.js";
 import { connectToServer } from "./server-connection.js";
 import { createCallToolWrapper } from "./tool-wrapper.js";
 import { buildConfig } from "./config-builder.js";
+// Issue #155: Import annotation debug mode setter
+import { setAnnotationDebugMode } from "../../../../client/lib/services/assessment/modules/annotations/AlignmentChecker.js";
 /**
  * Run full assessment against an MCP server
  *
@@ -22,6 +25,13 @@ import { buildConfig } from "./config-builder.js";
  * @returns Assessment results
  */
 export async function runFullAssessment(options) {
+    // Issue #155: Enable annotation debug mode if flag is set
+    if (options.debugAnnotations) {
+        setAnnotationDebugMode(true);
+        if (!options.jsonOnly) {
+            console.log("🔍 Annotation debug mode enabled (--debug-annotations)");
+        }
+    }
     if (!options.jsonOnly) {
         console.log(`\n🔍 Starting full assessment for: ${options.serverName}`);
     }
@@ -199,10 +209,19 @@ export async function runFullAssessment(options) {
         }
     }
     let sourceFiles = {};
-    if (options.sourceCodePath && fs.existsSync(options.sourceCodePath)) {
-        sourceFiles = loadSourceFiles(options.sourceCodePath);
-        if (!options.jsonOnly) {
-            console.log(`📁 Loaded source files from: ${options.sourceCodePath}`);
+    if (options.sourceCodePath) {
+        // Resolve path using utility (handles ~, relative paths, symlinks)
+        const resolvedSourcePath = resolveSourcePath(options.sourceCodePath);
+        if (fs.existsSync(resolvedSourcePath)) {
+            sourceFiles = loadSourceFiles(resolvedSourcePath, options.debugSource);
+            if (!options.jsonOnly) {
+                console.log(`📁 Loaded source files from: ${resolvedSourcePath}`);
+            }
+        }
+        else if (!options.jsonOnly) {
+            // Issue #154: Always show warning, not just with --debug-source
+            console.log(`⚠️  Source path not found: ${options.sourceCodePath} (resolved: ${resolvedSourcePath})`);
+            console.log(`   Use --source <existing-path> to enable full source file analysis.`);
         }
     }
     // Create readResource wrapper for ResourceAssessor

package/build/lib/assessment-runner/index.js

@@ -10,6 +10,8 @@
 export { loadServerConfig } from "./server-config.js";
 // Source File Loading
 export { loadSourceFiles } from "./source-loader.js";
+// Path Resolution
+export { resolveSourcePath } from "./path-resolver.js";
 // Server Connection
 export { connectToServer } from "./server-connection.js";
 // Tool Wrapper

package/build/lib/assessment-runner/path-resolver.js

@@ -0,0 +1,48 @@
+/**
+ * Path Resolution Utilities
+ *
+ * Handles path normalization for source code paths including:
+ * - Home directory (~) expansion
+ * - Relative path resolution
+ * - Symlink resolution (for MCPB temp extraction paths)
+ *
+ * @module cli/lib/assessment-runner/path-resolver
+ */
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+/**
+ * Resolve a source code path to an absolute, real path
+ *
+ * Handles:
+ * - Tilde (~) expansion to home directory
+ * - Relative paths resolved to absolute
+ * - Symlinks followed to real paths (important for MCPB temp extraction)
+ *
+ * @param sourcePath - The source path to resolve (may be relative, contain ~, or be a symlink)
+ * @returns The resolved absolute path, or the original path if resolution fails
+ *
+ * @example
+ * resolveSourcePath("~/project") // => "/home/user/project"
+ * resolveSourcePath("./src") // => "/current/working/dir/src"
+ * resolveSourcePath("/tmp/symlink") // => "/actual/target/path"
+ */
+export function resolveSourcePath(sourcePath) {
+    let resolved = sourcePath;
+    // Expand home directory (~)
+    if (resolved.startsWith("~")) {
+        resolved = path.join(os.homedir(), resolved.slice(1));
+    }
+    // Resolve to absolute path
+    resolved = path.resolve(resolved);
+    // Follow symlinks if path exists (handles MCPB temp extraction paths)
+    try {
+        if (fs.existsSync(resolved)) {
+            resolved = fs.realpathSync(resolved);
+        }
+    }
+    catch {
+        // realpathSync can fail on broken symlinks, continue with resolved path
+    }
+    return resolved;
+}

package/build/lib/assessment-runner/source-loader.js

@@ -6,6 +6,7 @@
  * @module cli/lib/assessment-runner/source-loader
  */
 import * as fs from "fs";
+import * as os from "os";
 import * as path from "path";
 /** Maximum file size (in characters) to include in source code analysis */
 const MAX_SOURCE_FILE_SIZE = 100_000;
@@ -13,34 +14,65 @@ const MAX_SOURCE_FILE_SIZE = 100_000;
  * Load optional files from source code path
  *
  * @param sourcePath - Path to source code directory
+ * @param debug - Enable debug logging for path resolution troubleshooting
  * @returns Object containing loaded source files
  */
-export function loadSourceFiles(sourcePath) {
+export function loadSourceFiles(sourcePath, debug = false) {
     const result = {};
+    // Debug logging helper - masks home directory for privacy in logs
+    const log = (msg) => {
+        if (!debug)
+            return;
+        const maskedMsg = msg.replace(os.homedir(), "~");
+        console.log(`[source-loader] ${maskedMsg}`);
+    };
+    log(`Starting source file loading from: ${sourcePath}`);
     // Search for README in source directory and parent directories (up to 3 levels)
     // This handles cases where --source points to a subdirectory but README is at repo root
-    const readmePaths = ["README.md", "readme.md", "Readme.md"];
+    // Extended patterns to handle various README naming conventions
+    const readmePaths = [
+        "README.md",
+        "readme.md",
+        "Readme.md",
+        "README.markdown",
+        "readme.markdown",
+        "README.txt",
+        "readme.txt",
+        "README",
+        "Readme",
+    ];
     let readmeFound = false;
+    log(`Searching for README variants: ${readmePaths.join(", ")}`);
     // First try the source directory itself
     for (const readmePath of readmePaths) {
         const fullPath = path.join(sourcePath, readmePath);
-        if (fs.existsSync(fullPath)) {
+        const exists = fs.existsSync(fullPath);
+        log(`  Checking: ${fullPath} - exists: ${exists}`);
+        if (exists) {
             result.readmeContent = fs.readFileSync(fullPath, "utf-8");
+            log(`  ✓ Found README: ${fullPath} (${result.readmeContent.length} bytes)`);
             readmeFound = true;
             break;
         }
     }
     // If not found, search parent directories (up to 3 levels)
     if (!readmeFound) {
+        log(`README not found in source directory, searching parent directories...`);
         let currentDir = sourcePath;
         for (let i = 0; i < 3; i++) {
             const parentDir = path.dirname(currentDir);
-            if (parentDir === currentDir)
+            if (parentDir === currentDir) {
+                log(`  Reached filesystem root, stopping parent search`);
                 break; // Reached filesystem root
+            }
+            log(`  Searching parent level ${i + 1}: ${parentDir}`);
             for (const readmePath of readmePaths) {
                 const fullPath = path.join(parentDir, readmePath);
-                if (fs.existsSync(fullPath)) {
+                const exists = fs.existsSync(fullPath);
+                log(`    Checking: ${fullPath} - exists: ${exists}`);
+                if (exists) {
                     result.readmeContent = fs.readFileSync(fullPath, "utf-8");
+                    log(`    ✓ Found README: ${fullPath} (${result.readmeContent.length} bytes)`);
                     readmeFound = true;
                     break;
                 }
@@ -50,6 +82,9 @@ export function loadSourceFiles(sourcePath) {
             currentDir = parentDir;
         }
     }
+    if (!readmeFound) {
+        log(`✗ No README found in source directory or parent directories`);
+    }
     const packagePath = path.join(sourcePath, "package.json");
     if (fs.existsSync(packagePath)) {
         result.packageJson = JSON.parse(fs.readFileSync(packagePath, "utf-8"));
@@ -135,5 +170,12 @@ export function loadSourceFiles(sourcePath) {
     catch (e) {
         console.warn("[Assessment] Could not load source files:", e);
     }
+    // Summary logging
+    const sourceCodeFiles = result.sourceCodeFiles;
+    log(`Source loading complete:`);
+    log(`  - README: ${result.readmeContent ? "found" : "not found"}`);
+    log(`  - package.json: ${result.packageJson ? "found" : "not found"}`);
+    log(`  - manifest.json: ${result.manifestJson ? "found" : "not found"}`);
+    log(`  - Source files loaded: ${sourceCodeFiles.size}`);
     return result;
 }

package/build/lib/cli-parser.js

@@ -94,6 +94,13 @@ export function parseArgs(argv) {
             case "--source":
                 options.sourceCodePath = args[++i];
                 break;
+            case "--debug-source":
+                options.debugSource = true;
+                break;
+            case "--debug-annotations":
+                // Issue #155: Enable debug logging for annotation extraction
+                options.debugAnnotations = true;
+                break;
             case "--pattern-config":
             case "-p":
                 options.patternConfigPath = args[++i];
@@ -374,6 +381,9 @@ Options:
   --config, -c <path>    Path to server config JSON
   --output, -o <path>    Output path (default: /tmp/inspector-full-assessment-<server>.<ext>)
   --source <path>        Source code path for deep analysis (AUP, portability, etc.)
+  --debug-source         Enable debug logging for source file loading (Issue #151)
+  --debug-annotations    Enable debug logging for annotation extraction (Issue #155)
+                         Shows raw tool keys, annotations object, and direct hints
   --pattern-config, -p <path>  Path to custom annotation pattern JSON
   --performance-config <path>  Path to performance tuning JSON (batch sizes, timeouts, etc.)
   --format, -f <type>    Output format: json (default) or markdown

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bryan-thompson/inspector-assessment-cli",
-  "version": "1.35.3",
+  "version": "1.36.1",
   "description": "CLI for the Enhanced MCP Inspector with assessment capabilities",
   "license": "MIT",
   "author": "Bryan Thompson <bryan@triepod.ai>",