@bryan-thompson/inspector-assessment 1.35.3 → 1.36.0

package/cli/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";
@@ -248,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/cli/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/cli/build/__tests__/assessment-runner/assessment-executor.test.js

@@ -216,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/cli/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/cli/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/cli/build/__tests__/assessment-runner/source-loader.test.js

@@ -80,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", () => {

package/cli/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/cli/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/cli/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";
@@ -104,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/cli/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/cli/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/cli/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/cli/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";
@@ -123,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/cli/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/cli/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/cli/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/cli/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/cli/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/cli/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;
+}