@bryan-thompson/inspector-assessment-client 1.25.1 → 1.25.5

package/lib/services/assessment/lib/timeoutUtils.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Timeout Utilities for Assessment Operations
+ *
+ * Provides AbortController-based timeout handling with proper cleanup.
+ * Fixes GitHub issue #38: Promise.race patterns that leave timers hanging.
+ *
+ * Key improvements over basic Promise.race:
+ * 1. Clears setTimeout when operation completes (prevents timer leaks)
+ * 2. Uses AbortController for signal-based cancellation
+ * 3. Provides consistent error messages
+ */
+export interface TimeoutOptions {
+    /** Timeout in milliseconds */
+    timeoutMs: number;
+    /** Optional custom error message for timeout */
+    errorMessage?: string;
+}
+/**
+ * Execute a promise with timeout and proper cleanup.
+ *
+ * This function wraps any promise with a timeout, ensuring the timer
+ * is always cleaned up whether the operation succeeds, fails, or times out.
+ *
+ * @param promise - The promise to execute
+ * @param options - Timeout configuration
+ * @returns The result of the promise
+ * @throws Error if operation times out
+ *
+ * @example Basic usage
+ * ```typescript
+ * const result = await executeWithTimeout(
+ *   callTool(tool.name, params),
+ *   { timeoutMs: 5000 }
+ * );
+ * ```
+ *
+ * @example With custom error message
+ * ```typescript
+ * const result = await executeWithTimeout(
+ *   fetchData(),
+ *   { timeoutMs: 10000, errorMessage: "Data fetch timed out" }
+ * );
+ * ```
+ */
+export declare function executeWithTimeout<T>(promise: Promise<T>, options: TimeoutOptions): Promise<T>;
+/**
+ * Execute an async function with timeout and AbortSignal support.
+ *
+ * This variant accepts a function that receives an AbortSignal, enabling
+ * cancellation of fetch requests and other abortable operations.
+ *
+ * @param fn - Function that accepts an AbortSignal and returns a Promise
+ * @param options - Timeout configuration
+ * @returns The result of the function
+ * @throws Error if operation times out
+ *
+ * @example With fetch
+ * ```typescript
+ * const data = await executeWithTimeoutAndSignal(
+ *   async (signal) => {
+ *     const response = await fetch(url, { signal });
+ *     return response.json();
+ *   },
+ *   { timeoutMs: 5000 }
+ * );
+ * ```
+ */
+export declare function executeWithTimeoutAndSignal<T>(fn: (signal: AbortSignal) => Promise<T>, options: TimeoutOptions): Promise<T>;
+//# sourceMappingURL=timeoutUtils.d.ts.map

package/lib/services/assessment/lib/timeoutUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeoutUtils.d.ts","sourceRoot":"","sources":["../../../../src/services/assessment/lib/timeoutUtils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,cAAc;IAC7B,8BAA8B;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,gDAAgD;IAChD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,EACxC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,CAAC,CAAC,CA2BZ;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,2BAA2B,CAAC,CAAC,EACjD,EAAE,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,EACvC,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,CAAC,CAAC,CAqBZ"}

package/lib/services/assessment/lib/timeoutUtils.js

@@ -0,0 +1,103 @@
+/**
+ * Timeout Utilities for Assessment Operations
+ *
+ * Provides AbortController-based timeout handling with proper cleanup.
+ * Fixes GitHub issue #38: Promise.race patterns that leave timers hanging.
+ *
+ * Key improvements over basic Promise.race:
+ * 1. Clears setTimeout when operation completes (prevents timer leaks)
+ * 2. Uses AbortController for signal-based cancellation
+ * 3. Provides consistent error messages
+ */
+/**
+ * Execute a promise with timeout and proper cleanup.
+ *
+ * This function wraps any promise with a timeout, ensuring the timer
+ * is always cleaned up whether the operation succeeds, fails, or times out.
+ *
+ * @param promise - The promise to execute
+ * @param options - Timeout configuration
+ * @returns The result of the promise
+ * @throws Error if operation times out
+ *
+ * @example Basic usage
+ * ```typescript
+ * const result = await executeWithTimeout(
+ *   callTool(tool.name, params),
+ *   { timeoutMs: 5000 }
+ * );
+ * ```
+ *
+ * @example With custom error message
+ * ```typescript
+ * const result = await executeWithTimeout(
+ *   fetchData(),
+ *   { timeoutMs: 10000, errorMessage: "Data fetch timed out" }
+ * );
+ * ```
+ */
+export async function executeWithTimeout(promise, options) {
+    const { timeoutMs, errorMessage } = options;
+    // Create abort controller for timeout signaling
+    const controller = new AbortController();
+    // Set up timeout that triggers abort
+    const timeoutId = setTimeout(() => {
+        controller.abort();
+    }, timeoutMs);
+    // Create timeout promise that rejects when abort signal fires
+    const timeoutPromise = new Promise((_, reject) => {
+        controller.signal.addEventListener("abort", () => {
+            reject(new Error(errorMessage ?? `Operation timed out after ${timeoutMs}ms`));
+        });
+    });
+    try {
+        // Race the operation against timeout
+        return await Promise.race([promise, timeoutPromise]);
+    }
+    finally {
+        // CRITICAL: Always clean up timer to prevent leaks
+        clearTimeout(timeoutId);
+    }
+}
+/**
+ * Execute an async function with timeout and AbortSignal support.
+ *
+ * This variant accepts a function that receives an AbortSignal, enabling
+ * cancellation of fetch requests and other abortable operations.
+ *
+ * @param fn - Function that accepts an AbortSignal and returns a Promise
+ * @param options - Timeout configuration
+ * @returns The result of the function
+ * @throws Error if operation times out
+ *
+ * @example With fetch
+ * ```typescript
+ * const data = await executeWithTimeoutAndSignal(
+ *   async (signal) => {
+ *     const response = await fetch(url, { signal });
+ *     return response.json();
+ *   },
+ *   { timeoutMs: 5000 }
+ * );
+ * ```
+ */
+export async function executeWithTimeoutAndSignal(fn, options) {
+    const { timeoutMs, errorMessage } = options;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => {
+        controller.abort();
+    }, timeoutMs);
+    try {
+        return await fn(controller.signal);
+    }
+    catch (error) {
+        // Convert AbortError to timeout error for consistency
+        if (error instanceof Error && error.name === "AbortError") {
+            throw new Error(errorMessage ?? `Operation timed out after ${timeoutMs}ms`);
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}

package/lib/services/assessment/modules/BaseAssessor.d.ts

@@ -5,10 +5,12 @@
 import { AssessmentConfiguration, AssessmentStatus } from "../../../lib/assessmentTypes.js";
 import { AssessmentContext } from "../AssessmentOrchestrator.js";
 import { Logger } from "../lib/logger.js";
+import { ErrorResult } from "../lib/errors.js";
 export declare abstract class BaseAssessor<T = unknown> {
     protected config: AssessmentConfiguration;
     protected logger: Logger;
     protected testCount: number;
+    private deprecationWarningsEmitted;
     constructor(config: AssessmentConfiguration);
     /**
      * Abstract method that each assessor must implement
@@ -20,14 +22,39 @@ export declare abstract class BaseAssessor<T = unknown> {
     protected determineStatus(passed: number, total: number, threshold?: number): AssessmentStatus;
     /**
      * Log assessment progress
-     * @deprecated Use this.logger.info() directly for structured logging with context
+     * @deprecated Use this.logger.info() directly for structured logging with context. Will be removed in v2.0.0.
      */
     protected log(message: string): void;
     /**
-     * Log error
-     * @deprecated Use this.logger.error() directly for structured logging with context
+     * Log error with optional context
+     * @deprecated Use this.logger.error() directly for structured logging with context. Will be removed in v2.0.0.
+     *
+     * @param message - Description of what operation failed
+     * @param error - The error that occurred (optional)
      */
     protected logError(message: string, error?: unknown): void;
+    /**
+     * Handle an error with logging and structured result
+     *
+     * Use this method in catch blocks to ensure consistent error handling:
+     * 1. Logs the error with context
+     * 2. Categorizes the error automatically
+     * 3. Returns a structured result with error info
+     *
+     * @param error - The caught error
+     * @param context - Description of what operation failed
+     * @param defaults - Default values to merge into result
+     * @returns A result object with error information
+     *
+     * @example
+     * try {
+     *   const result = await this.callTool(tool);
+     *   return { passed: true, result };
+     * } catch (error) {
+     *   return this.handleError(error, `Failed to call tool ${tool.name}`, { passed: false });
+     * }
+     */
+    protected handleError<T extends ErrorResult>(error: unknown, context: string, defaults?: Partial<T>): T;
     /**
      * Get test count for this assessor
      */
@@ -45,17 +72,25 @@ export declare abstract class BaseAssessor<T = unknown> {
      */
     protected sleep(ms: number): Promise<void>;
     /**
-     * Execute with timeout
+     * Execute with timeout and proper cleanup.
+     *
+     * Uses AbortController-based timeout handling that clears the timer
+     * when the operation completes, preventing timer leaks.
+     *
+     * @param promise - The promise to execute
+     * @param timeoutMs - Timeout in milliseconds (defaults to config.testTimeout)
+     * @returns The result of the promise
+     * @throws Error if operation times out
      */
     protected executeWithTimeout<T>(promise: Promise<T>, timeoutMs?: number): Promise<T>;
     /**
      * Safe JSON parse with error handling
      */
-    protected safeJsonParse(text: string): any;
+    protected safeJsonParse(text: string): unknown;
     /**
      * Extract error message from various error types
      */
-    protected extractErrorMessage(error: any): string;
+    protected extractErrorMessage(error: unknown): string;
     /**
      * Check if a response indicates an error
      * Handles various MCP response formats
@@ -63,11 +98,11 @@ export declare abstract class BaseAssessor<T = unknown> {
      * @param response - The response to check
      * @param strictMode - If true, only check explicit error indicators (default: false)
      */
-    protected isErrorResponse(response: any, strictMode?: boolean): boolean;
+    protected isErrorResponse(response: unknown, strictMode?: boolean): boolean;
     /**
      * Extract error information from a response
      */
-    protected extractErrorInfo(response: any): {
+    protected extractErrorInfo(response: unknown): {
         code?: string | number;
         message?: string;
     };

package/lib/services/assessment/modules/BaseAssessor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BaseAssessor.d.ts","sourceRoot":"","sources":["../../../../src/services/assessment/modules/BaseAssessor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,uBAAuB,EACvB,gBAAgB,EACjB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAAE,MAAM,EAAwC,MAAM,eAAe,CAAC;AAE7E,8BAAsB,YAAY,CAAC,CAAC,GAAG,OAAO;IAC5C,SAAS,CAAC,MAAM,EAAE,uBAAuB,CAAC;IAC1C,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,SAAS,EAAE,MAAM,CAAK;gBAEpB,MAAM,EAAE,uBAAuB;IAS3C;;OAEG;IACH,QAAQ,CAAC,MAAM,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,CAAC,CAAC;IAEvD;;OAEG;IACH,SAAS,CAAC,eAAe,CACvB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,SAAS,GAAE,MAAY,GACtB,gBAAgB;IAUnB;;;OAGG;IACH,SAAS,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAIpC;;;OAGG;IACH,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,IAAI;IAI1D;;OAEG;IACH,YAAY,IAAI,MAAM;IAItB;;OAEG;IACH,cAAc,IAAI,IAAI;IAItB;;OAEG;IACH,SAAS,CAAC,gBAAgB,CACxB,OAAO,EAAE,MAAM,uBAAuB,CAAC,sBAAsB,CAAC,GAC7D,OAAO;IAIV;;OAEG;cACa,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhD;;OAEG;cACa,kBAAkB,CAAC,CAAC,EAClC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,SAAS,GAAE,MAAgC,GAC1C,OAAO,CAAC,CAAC,CAAC;IAWb;;OAEG;IACH,SAAS,CAAC,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG;IAS1C;;OAEG;IACH,SAAS,CAAC,mBAAmB,CAAC,KAAK,EAAE,GAAG,GAAG,MAAM;IAejD;;;;;;OAMG;IACH,SAAS,CAAC,eAAe,CACvB,QAAQ,EAAE,GAAG,EACb,UAAU,GAAE,OAAe,GAC1B,OAAO;IA8CV;;OAEG;IACH,SAAS,CAAC,gBAAgB,CAAC,QAAQ,EAAE,GAAG,GAAG;QACzC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;QACvB,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB;CAqBF"}
+{"version":3,"file":"BaseAssessor.d.ts","sourceRoot":"","sources":["../../../../src/services/assessment/modules/BaseAssessor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,uBAAuB,EACvB,gBAAgB,EAEjB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAAE,MAAM,EAAwC,MAAM,eAAe,CAAC;AAC7E,OAAO,EAGL,WAAW,EAEZ,MAAM,eAAe,CAAC;AAGvB,8BAAsB,YAAY,CAAC,CAAC,GAAG,OAAO;IAC5C,SAAS,CAAC,MAAM,EAAE,uBAAuB,CAAC;IAC1C,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,SAAS,EAAE,MAAM,CAAK;IAGhC,OAAO,CAAC,0BAA0B,CAGhC;gBAEU,MAAM,EAAE,uBAAuB;IAS3C;;OAEG;IACH,QAAQ,CAAC,MAAM,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,CAAC,CAAC;IAEvD;;OAEG;IACH,SAAS,CAAC,eAAe,CACvB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,SAAS,GAAE,MAAY,GACtB,gBAAgB;IAUnB;;;OAGG;IACH,SAAS,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAWpC;;;;;;OAMG;IACH,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,IAAI;IAW1D;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,SAAS,CAAC,WAAW,CAAC,CAAC,SAAS,WAAW,EACzC,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,MAAM,EACf,QAAQ,GAAE,OAAO,CAAC,CAAC,CAAM,GACxB,CAAC;IAsBJ;;OAEG;IACH,YAAY,IAAI,MAAM;IAItB;;OAEG;IACH,cAAc,IAAI,IAAI;IAItB;;OAEG;IACH,SAAS,CAAC,gBAAgB,CACxB,OAAO,EAAE,MAAM,uBAAuB,CAAC,sBAAsB,CAAC,GAC7D,OAAO;IAIV;;OAEG;cACa,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhD;;;;;;;;;;OAUG;cACa,kBAAkB,CAAC,CAAC,EAClC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,SAAS,GAAE,MAAgC,GAC1C,OAAO,CAAC,CAAC,CAAC;IAOb;;OAEG;IACH,SAAS,CAAC,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAS9C;;OAEG;IACH,SAAS,CAAC,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM;IAgBrD;;;;;;OAMG;IACH,SAAS,CAAC,eAAe,CACvB,QAAQ,EAAE,OAAO,EACjB,UAAU,GAAE,OAAe,GAC1B,OAAO;IA+CV;;OAEG;IACH,SAAS,CAAC,gBAAgB,CAAC,QAAQ,EAAE,OAAO,GAAG;QAC7C,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;QACvB,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB;CA2BF"}

package/lib/services/assessment/modules/BaseAssessor.js

@@ -3,10 +3,17 @@
  * Provides common functionality for all assessment modules
  */
 import { createLogger, DEFAULT_LOGGING_CONFIG } from "../lib/logger.js";
+import { ErrorCategory, categorizeError, } from "../lib/errors.js";
+import { executeWithTimeout as executeWithTimeoutUtil } from "../lib/timeoutUtils.js";
 export class BaseAssessor {
     config;
     logger;
     testCount = 0;
+    // Track deprecation warnings to emit only once per instance
+    deprecationWarningsEmitted = {
+        log: false,
+        logError: false,
+    };
     constructor(config) {
         this.config = config;
         // Create logger from config, using class name as prefix
@@ -27,18 +34,70 @@ export class BaseAssessor {
     }
     /**
      * Log assessment progress
-     * @deprecated Use this.logger.info() directly for structured logging with context
+     * @deprecated Use this.logger.info() directly for structured logging with context. Will be removed in v2.0.0.
      */
     log(message) {
+        if (!this.deprecationWarningsEmitted.log) {
+            this.logger.warn("BaseAssessor.log() is deprecated. Use this.logger.info() instead. " +
+                "This method will be removed in v2.0.0.");
+            this.deprecationWarningsEmitted.log = true;
+        }
         this.logger.info(message);
     }
     /**
-     * Log error
-     * @deprecated Use this.logger.error() directly for structured logging with context
+     * Log error with optional context
+     * @deprecated Use this.logger.error() directly for structured logging with context. Will be removed in v2.0.0.
+     *
+     * @param message - Description of what operation failed
+     * @param error - The error that occurred (optional)
      */
     logError(message, error) {
+        if (!this.deprecationWarningsEmitted.logError) {
+            this.logger.warn("BaseAssessor.logError() is deprecated. Use this.logger.error() instead. " +
+                "This method will be removed in v2.0.0.");
+            this.deprecationWarningsEmitted.logError = true;
+        }
         this.logger.error(message, error ? { error: String(error) } : undefined);
     }
+    /**
+     * Handle an error with logging and structured result
+     *
+     * Use this method in catch blocks to ensure consistent error handling:
+     * 1. Logs the error with context
+     * 2. Categorizes the error automatically
+     * 3. Returns a structured result with error info
+     *
+     * @param error - The caught error
+     * @param context - Description of what operation failed
+     * @param defaults - Default values to merge into result
+     * @returns A result object with error information
+     *
+     * @example
+     * try {
+     *   const result = await this.callTool(tool);
+     *   return { passed: true, result };
+     * } catch (error) {
+     *   return this.handleError(error, `Failed to call tool ${tool.name}`, { passed: false });
+     * }
+     */
+    handleError(error, context, defaults = {}) {
+        const category = categorizeError(error);
+        const message = this.extractErrorMessage(error);
+        this.logger.error(context, {
+            error: message,
+            category,
+        });
+        const errorInfo = {
+            message,
+            code: category,
+            recoverable: category !== ErrorCategory.CONNECTION,
+            stack: error instanceof Error ? error.stack : undefined,
+        };
+        return {
+            ...defaults,
+            error: errorInfo,
+        };
+    }
     /**
      * Get test count for this assessor
      */
@@ -64,13 +123,21 @@ export class BaseAssessor {
         return new Promise((resolve) => setTimeout(resolve, ms));
     }
     /**
-     * Execute with timeout
+     * Execute with timeout and proper cleanup.
+     *
+     * Uses AbortController-based timeout handling that clears the timer
+     * when the operation completes, preventing timer leaks.
+     *
+     * @param promise - The promise to execute
+     * @param timeoutMs - Timeout in milliseconds (defaults to config.testTimeout)
+     * @returns The result of the promise
+     * @throws Error if operation times out
      */
     async executeWithTimeout(promise, timeoutMs = this.config.testTimeout) {
-        const timeoutPromise = new Promise((_, reject) => {
-            setTimeout(() => reject(new Error(`Operation timed out after ${timeoutMs}ms`)), timeoutMs);
+        return executeWithTimeoutUtil(promise, {
+            timeoutMs,
+            errorMessage: `Operation timed out after ${timeoutMs}ms`,
         });
-        return Promise.race([promise, timeoutPromise]);
     }
     /**
      * Safe JSON parse with error handling
@@ -90,17 +157,19 @@ export class BaseAssessor {
     extractErrorMessage(error) {
         if (typeof error === "string")
             return error;
-        if (error?.message)
-            return error.message;
-        if (error?.error)
-            return this.extractErrorMessage(error.error);
-        if (error?.content) {
-            if (Array.isArray(error.content)) {
-                return error.content
-                    .map((c) => c.text || c.content || "")
-                    .join(" ");
+        if (error && typeof error === "object") {
+            const err = error;
+            if (err.message && typeof err.message === "string")
+                return err.message;
+            if (err.error)
+                return this.extractErrorMessage(err.error);
+            if (err.content) {
+                if (Array.isArray(err.content)) {
+                    return err.content.map((c) => c.text || "").join(" ");
+                }
+                if (typeof err.content === "string")
+                    return err.content;
             }
-            return error.content;
         }
         return JSON.stringify(error);
     }
@@ -112,10 +181,11 @@ export class BaseAssessor {
      * @param strictMode - If true, only check explicit error indicators (default: false)
      */
     isErrorResponse(response, strictMode = false) {
-        if (!response)
+        if (!response || typeof response !== "object")
             return false;
+        const resp = response;
         // Check explicit error flag first (always check these)
-        if (response.isError === true || response.error !== undefined) {
+        if (resp.isError === true || resp.error !== undefined) {
             return true;
         }
         // In strict mode, only rely on explicit error indicators
@@ -125,9 +195,9 @@ export class BaseAssessor {
         }
         // In non-strict mode, also check content for error patterns
         // Used by ErrorHandlingAssessor where we're deliberately triggering errors
-        if (response.content) {
-            if (typeof response.content === "string") {
-                const lower = response.content.toLowerCase();
+        if (resp.content) {
+            if (typeof resp.content === "string") {
+                const lower = resp.content.toLowerCase();
                 // Only flag if error appears at start or with strong indicators
                 return (lower.startsWith("error:") ||
                     lower.startsWith("error ") ||
@@ -135,9 +205,9 @@ export class BaseAssessor {
                     lower.includes("failed to") ||
                     lower.includes("exception:"));
             }
-            else if (Array.isArray(response.content)) {
+            else if (Array.isArray(resp.content)) {
                 // Check if any text content starts with error indicators
-                return response.content.some((c) => {
+                return resp.content.some((c) => {
                     if (c.type !== "text" || !c.text)
                         return false;
                     const lower = c.text.toLowerCase();
@@ -155,23 +225,22 @@ export class BaseAssessor {
      * Extract error information from a response
      */
     extractErrorInfo(response) {
-        if (!response)
+        if (!response || typeof response !== "object")
             return {};
+        const resp = response;
         // Extract text from content array if present
         let contentText;
-        if (Array.isArray(response.content)) {
-            const textContent = response.content.find((c) => c.type === "text");
+        if (Array.isArray(resp.content)) {
+            const textContent = resp.content.find((c) => c.type === "text");
             contentText = textContent?.text;
         }
-        else if (typeof response.content === "string") {
-            contentText = response.content;
+        else if (typeof resp.content === "string") {
+            contentText = resp.content;
         }
+        const error = resp.error;
         return {
-            code: response.errorCode || response.code || response.error?.code,
-            message: response.errorMessage ||
-                response.message ||
-                response.error?.message ||
-                contentText,
+            code: (resp.errorCode ?? resp.code ?? error?.code),
+            message: (resp.errorMessage ?? resp.message ?? error?.message) || contentText,
         };
     }
 }

package/lib/services/assessment/modules/DeveloperExperienceAssessor.d.ts

@@ -51,7 +51,44 @@ export declare class DeveloperExperienceAssessor extends BaseAssessor<DeveloperE
     private extractSection;
     private extractSectionHeadings;
     private classifyCodeExample;
-    private calculateDocumentationScore;
+    /**
+     * Assess documentation quality using Issue #55 point-based scoring
+     * Max 100 points: README (30), Install (20), Config (20), Examples (20), License (10)
+     */
+    private assessDocumentationQuality;
+    /**
+     * Determine README quality tier based on size
+     * - minimal: <5KB
+     * - adequate: 5KB-15KB
+     * - comprehensive: >15KB
+     */
+    private determineReadmeQuality;
+    /**
+     * Calculate point-based quality score per Issue #55
+     * Max 100 points:
+     * - README exists: +10
+     * - README >5KB: +10 (adequate)
+     * - README >15KB: +10 more (comprehensive = +20 total)
+     * - Installation section: +20
+     * - Configuration section: +20
+     * - Examples present: +20
+     * - License file: +10
+     */
+    private calculateQualityScore;
+    /**
+     * Check for configuration/environment section
+     * Looks for: configuration, config, environment, env vars, .env
+     */
+    private checkConfigurationSection;
+    /**
+     * Detect license presence from context
+     * Checks sourceCodeFiles for LICENSE/LICENSE.md or README for license section
+     */
+    private detectLicense;
+    /**
+     * Detect license type (MIT, Apache-2.0, GPL, BSD, etc.)
+     */
+    private detectLicenseType;
     private analyzeUsability;
     private analyzeNamingConvention;
     private analyzeParameterClarity;

package/lib/services/assessment/modules/DeveloperExperienceAssessor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DeveloperExperienceAssessor.d.ts","sourceRoot":"","sources":["../../../../src/services/assessment/modules/DeveloperExperienceAssessor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAEhB,gBAAgB,EAEjB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAE9D;;GAEG;AACH,MAAM,WAAW,6BAA6B;IAC5C,yCAAyC;IACzC,aAAa,EAAE,oBAAoB,CAAC;IACpC,qCAAqC;IACrC,SAAS,EAAE,gBAAgB,CAAC;IAC5B,gDAAgD;IAChD,MAAM,EAAE,gBAAgB,CAAC;IACzB,iCAAiC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,sCAAsC;IACtC,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,iDAAiD;IACjD,MAAM,EAAE;QACN,aAAa,EAAE,MAAM,CAAC;QACtB,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;CACH;AAED,qBAAa,2BAA4B,SAAQ,YAAY,CAAC,6BAA6B,CAAC;IACpF,MAAM,CACV,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,6BAA6B,CAAC;IAuDzC,OAAO,CAAC,oBAAoB;IAmH5B,OAAO,CAAC,yBAAyB;IA4CjC,OAAO,CAAC,wBAAwB;IAiBhC,OAAO,CAAC,sBAAsB;IA8B9B,OAAO,CAAC,aAAa;IAKrB,OAAO,CAAC,mBAAmB;IAoB3B,OAAO,CAAC,mBAAmB;IAwC3B,OAAO,CAAC,wBAAwB;IAahC,OAAO,CAAC,eAAe;IAYvB,OAAO,CAAC,iBAAiB;IAczB,OAAO,CAAC,cAAc;IAStB,OAAO,CAAC,sBAAsB;IAY9B,OAAO,CAAC,mBAAmB;IAyB3B,OAAO,CAAC,2BAA2B;IAiBnC,OAAO,CAAC,gBAAgB;IAcxB,OAAO,CAAC,uBAAuB;IAoC/B,OAAO,CAAC,uBAAuB;IAsC/B,OAAO,CAAC,iBAAiB;IAczB,OAAO,CAAC,kBAAkB;IAsC1B,OAAO,CAAC,iBAAiB;IAiCzB,OAAO,CAAC,aAAa;IAQrB,OAAO,CAAC,uBAAuB;IAgB/B,OAAO,CAAC,sBAAsB;IAM9B,OAAO,CAAC,mBAAmB;IAyC3B,OAAO,CAAC,uBAAuB;CAmDhC"}
+{"version":3,"file":"DeveloperExperienceAssessor.d.ts","sourceRoot":"","sources":["../../../../src/services/assessment/modules/DeveloperExperienceAssessor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAEhB,gBAAgB,EAIjB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAE9D;;GAEG;AACH,MAAM,WAAW,6BAA6B;IAC5C,yCAAyC;IACzC,aAAa,EAAE,oBAAoB,CAAC;IACpC,qCAAqC;IACrC,SAAS,EAAE,gBAAgB,CAAC;IAC5B,gDAAgD;IAChD,MAAM,EAAE,gBAAgB,CAAC;IACzB,iCAAiC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,sCAAsC;IACtC,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,iDAAiD;IACjD,MAAM,EAAE;QACN,aAAa,EAAE,MAAM,CAAC;QACtB,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;CACH;AAED,qBAAa,2BAA4B,SAAQ,YAAY,CAAC,6BAA6B,CAAC;IACpF,MAAM,CACV,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,6BAA6B,CAAC;IAsEzC,OAAO,CAAC,oBAAoB;IAmH5B,OAAO,CAAC,yBAAyB;IA4CjC,OAAO,CAAC,wBAAwB;IAiBhC,OAAO,CAAC,sBAAsB;IA8B9B,OAAO,CAAC,aAAa;IAKrB,OAAO,CAAC,mBAAmB;IAoB3B,OAAO,CAAC,mBAAmB;IAwC3B,OAAO,CAAC,wBAAwB;IAahC,OAAO,CAAC,eAAe;IAYvB,OAAO,CAAC,iBAAiB;IAczB,OAAO,CAAC,cAAc;IAStB,OAAO,CAAC,sBAAsB;IAY9B,OAAO,CAAC,mBAAmB;IA6B3B;;;OAGG;IACH,OAAO,CAAC,0BAA0B;IAkBlC;;;;;OAKG;IACH,OAAO,CAAC,sBAAsB;IAW9B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,qBAAqB;IAgC7B;;;OAGG;IACH,OAAO,CAAC,yBAAyB;IAgBjC;;;OAGG;IACH,OAAO,CAAC,aAAa;IAoBrB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAsEzB,OAAO,CAAC,gBAAgB;IAcxB,OAAO,CAAC,uBAAuB;IAoC/B,OAAO,CAAC,uBAAuB;IAsC/B,OAAO,CAAC,iBAAiB;IAczB,OAAO,CAAC,kBAAkB;IAsC1B,OAAO,CAAC,iBAAiB;IAiCzB,OAAO,CAAC,aAAa;IAQrB,OAAO,CAAC,uBAAuB;IAgB/B,OAAO,CAAC,sBAAsB;IAM9B,OAAO,CAAC,mBAAmB;IAyC3B,OAAO,CAAC,uBAAuB;CAmDhC"}