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

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"}

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

@@ -16,20 +16,28 @@ import { BaseAssessor } from "./BaseAssessor.js";
 export class DeveloperExperienceAssessor extends BaseAssessor {
     async assess(context) {
         this.log("Starting developer experience assessment");
+        const readmeContent = context.readmeContent || "";
         // Assess documentation
-        const documentationMetrics = this.analyzeDocumentation(context.readmeContent || "", context.tools, "verbose");
-        const documentationScore = this.calculateDocumentationScore(documentationMetrics);
+        const documentationMetrics = this.analyzeDocumentation(readmeContent, context.tools, "verbose");
+        // Issue #55: Add quality scoring
+        const { checks: qualityChecks, score: qualityScore } = this.assessDocumentationQuality(readmeContent, context);
+        // Add quality data to metrics
+        documentationMetrics.qualityChecks = qualityChecks;
+        documentationMetrics.qualityScore = qualityScore;
+        documentationMetrics.readmeSizeBytes = Buffer.byteLength(readmeContent, "utf8");
+        // Use quality score for documentation scoring (Issue #55)
+        const documentationScore = qualityScore.total;
         // Assess usability
         const usabilityMetrics = this.analyzeUsability(context.tools);
         const usabilityScore = this.calculateUsabilityScore(usabilityMetrics);
-        // Calculate overall score (weighted average)
+        // Calculate overall score (weighted average: 60% docs, 40% usability)
         const overallScore = Math.round(documentationScore * 0.6 + usabilityScore * 0.4);
-        // Determine status
+        // Determine status using Issue #55 thresholds
         const status = this.determineOverallStatus(overallScore);
         // Generate explanation and recommendations
         const explanation = this.generateExplanation(documentationMetrics, usabilityMetrics, context.tools);
         const recommendations = this.generateRecommendations(documentationMetrics, usabilityMetrics);
-        this.testCount = 9; // Documentation (5) + Usability (4) checks
+        this.testCount = 15; // Documentation (5) + Quality (6) + Usability (4) checks
         return {
             documentation: documentationMetrics,
             usability: usabilityMetrics,
@@ -321,20 +329,178 @@ export class DeveloperExperienceAssessor extends BaseAssessor {
         }
         return "functional";
     }
-    calculateDocumentationScore(metrics) {
-        let score = 0;
-        const maxScore = 5;
-        if (metrics.hasReadme)
-            score++;
-        if (metrics.hasInstallInstructions)
-            score++;
-        if (metrics.hasUsageGuide)
-            score++;
-        if (metrics.hasAPIReference)
-            score++;
-        if (metrics.exampleCount >= metrics.requiredExamples)
-            score++;
-        return Math.round((score / maxScore) * 100);
+    // ============================================================================
+    // Issue #55: Documentation Quality Scoring
+    // ============================================================================
+    /**
+     * Assess documentation quality using Issue #55 point-based scoring
+     * Max 100 points: README (30), Install (20), Config (20), Examples (20), License (10)
+     */
+    assessDocumentationQuality(content, context) {
+        const checks = {
+            hasReadme: content.length > 0,
+            readmeQuality: this.determineReadmeQuality(content),
+            hasInstallation: this.checkInstallInstructions(content),
+            hasConfiguration: this.checkConfigurationSection(content),
+            hasExamples: this.checkUsageGuide(content),
+            hasLicense: this.detectLicense(context),
+            licenseType: this.detectLicenseType(context),
+        };
+        const score = this.calculateQualityScore(checks, content);
+        return { checks, score };
+    }
+    /**
+     * Determine README quality tier based on size
+     * - minimal: <5KB
+     * - adequate: 5KB-15KB
+     * - comprehensive: >15KB
+     */
+    determineReadmeQuality(content) {
+        const sizeBytes = Buffer.byteLength(content, "utf8");
+        const sizeKB = sizeBytes / 1024;
+        if (sizeKB > 15)
+            return "comprehensive";
+        if (sizeKB > 5)
+            return "adequate";
+        return "minimal";
+    }
+    /**
+     * 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
+     */
+    calculateQualityScore(checks, content) {
+        const sizeBytes = Buffer.byteLength(content, "utf8");
+        const sizeKB = sizeBytes / 1024;
+        // Calculate README size bonus
+        let readmeComprehensive = 0;
+        if (checks.hasReadme) {
+            if (sizeKB > 15) {
+                readmeComprehensive = 20; // comprehensive: +10 + +10
+            }
+            else if (sizeKB > 5) {
+                readmeComprehensive = 10; // adequate: +10
+            }
+        }
+        const breakdown = {
+            readmeExists: checks.hasReadme ? 10 : 0,
+            readmeComprehensive,
+            installation: checks.hasInstallation ? 20 : 0,
+            configuration: checks.hasConfiguration ? 20 : 0,
+            examples: checks.hasExamples ? 20 : 0,
+            license: checks.hasLicense ? 10 : 0,
+        };
+        return {
+            total: Object.values(breakdown).reduce((sum, v) => sum + v, 0),
+            breakdown,
+        };
+    }
+    /**
+     * Check for configuration/environment section
+     * Looks for: configuration, config, environment, env vars, .env
+     */
+    checkConfigurationSection(content) {
+        const configKeywords = [
+            "configuration",
+            "config",
+            "environment variable",
+            "env var",
+            ".env",
+            "api key",
+            "api_key",
+            "apikey",
+            "setup",
+        ];
+        const contentLower = content.toLowerCase();
+        return configKeywords.some((keyword) => contentLower.includes(keyword));
+    }
+    /**
+     * Detect license presence from context
+     * Checks sourceCodeFiles for LICENSE/LICENSE.md or README for license section
+     */
+    detectLicense(context) {
+        // Check source code files if available
+        if (context.sourceCodeFiles) {
+            const licenseFiles = [
+                "LICENSE",
+                "LICENSE.md",
+                "LICENSE.txt",
+                "LICENCE",
+                "LICENCE.md",
+            ];
+            for (const file of licenseFiles) {
+                if (context.sourceCodeFiles.has(file))
+                    return true;
+            }
+        }
+        // Fallback: check README for license section
+        const content = context.readmeContent || "";
+        return /^#+\s*licen[sc]e/im.test(content);
+    }
+    /**
+     * Detect license type (MIT, Apache-2.0, GPL, BSD, etc.)
+     */
+    detectLicenseType(context) {
+        if (!context.sourceCodeFiles)
+            return undefined;
+        // Try common license file names
+        const licenseFiles = [
+            "LICENSE",
+            "LICENSE.md",
+            "LICENSE.txt",
+            "LICENCE",
+            "LICENCE.md",
+        ];
+        let licenseContent;
+        for (const file of licenseFiles) {
+            if (context.sourceCodeFiles.has(file)) {
+                licenseContent = context.sourceCodeFiles.get(file);
+                break;
+            }
+        }
+        if (!licenseContent)
+            return undefined;
+        // Simple license detection patterns
+        if (licenseContent.includes("MIT License") ||
+            licenseContent.includes("Permission is hereby granted, free of charge")) {
+            return "MIT";
+        }
+        if (licenseContent.includes("Apache License") &&
+            licenseContent.includes("2.0")) {
+            return "Apache-2.0";
+        }
+        if (licenseContent.includes("GNU GENERAL PUBLIC LICENSE")) {
+            if (licenseContent.includes("Version 3"))
+                return "GPL-3.0";
+            if (licenseContent.includes("Version 2"))
+                return "GPL-2.0";
+            return "GPL";
+        }
+        if (licenseContent.includes("BSD")) {
+            if (licenseContent.includes("3-Clause") || licenseContent.includes("New"))
+                return "BSD-3-Clause";
+            if (licenseContent.includes("2-Clause") ||
+                licenseContent.includes("Simplified"))
+                return "BSD-2-Clause";
+            return "BSD";
+        }
+        if (licenseContent.includes("ISC License")) {
+            return "ISC";
+        }
+        if (licenseContent.includes("Mozilla Public License")) {
+            return "MPL-2.0";
+        }
+        if (licenseContent.includes("UNLICENSE") ||
+            licenseContent.includes("unlicense")) {
+            return "Unlicense";
+        }
+        return "Unknown";
     }
     // ============================================================================
     // Usability Analysis (from UsabilityAssessor)

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

@@ -3,9 +3,14 @@
  * Evaluates documentation quality and completeness
  */
 import { DocumentationAssessment } from "../../../lib/assessmentTypes.js";
+import { AssessmentConfiguration } from "../../../lib/assessment/configTypes.js";
 import { BaseAssessor } from "./BaseAssessor.js";
 import { AssessmentContext } from "../AssessmentOrchestrator.js";
+/**
+ * @deprecated Use DeveloperExperienceAssessor instead. Will be removed in v2.0.0.
+ */
 export declare class DocumentationAssessor extends BaseAssessor {
+    constructor(config: AssessmentConfiguration);
     assess(context: AssessmentContext): Promise<DocumentationAssessment>;
     private analyzeDocumentation;
     /**

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

@@ -1 +1 @@
-{"version":3,"file":"DocumentationAssessor.d.ts","sourceRoot":"","sources":["../../../../src/services/assessment/modules/DocumentationAssessor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,uBAAuB,EAKxB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAE9D,qBAAa,qBAAsB,SAAQ,YAAY;IAC/C,MAAM,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,uBAAuB,CAAC;IAyC1E,OAAO,CAAC,oBAAoB;IAuJ5B;;;OAGG;IACH,OAAO,CAAC,yBAAyB;IAuEjC;;OAEG;IACH,OAAO,CAAC,wBAAwB;IAiBhC;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAmC9B;;OAEG;IACH,OAAO,CAAC,aAAa;IAKrB;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAqB3B;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IA4C3B,OAAO,CAAC,wBAAwB;IAchC,OAAO,CAAC,eAAe;IAavB,OAAO,CAAC,iBAAiB;IAezB,OAAO,CAAC,cAAc;IAUtB;;;OAGG;IACH,OAAO,CAAC,sBAAsB;IAY9B;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IA4B3B,OAAO,CAAC,4BAA4B;IAmBpC,OAAO,CAAC,mBAAmB;IAyB3B,OAAO,CAAC,uBAAuB;CA+BhC"}
+{"version":3,"file":"DocumentationAssessor.d.ts","sourceRoot":"","sources":["../../../../src/services/assessment/modules/DocumentationAssessor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,uBAAuB,EAKxB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AACvE,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAE9D;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,YAAY;gBACzC,MAAM,EAAE,uBAAuB;IAYrC,MAAM,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,uBAAuB,CAAC;IAyC1E,OAAO,CAAC,oBAAoB;IAuJ5B;;;OAGG;IACH,OAAO,CAAC,yBAAyB;IAuEjC;;OAEG;IACH,OAAO,CAAC,wBAAwB;IAiBhC;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAmC9B;;OAEG;IACH,OAAO,CAAC,aAAa;IAKrB;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAqB3B;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IA4C3B,OAAO,CAAC,wBAAwB;IAchC,OAAO,CAAC,eAAe;IAavB,OAAO,CAAC,iBAAiB;IAezB,OAAO,CAAC,cAAc;IAUtB;;;OAGG;IACH,OAAO,CAAC,sBAAsB;IAY9B;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IA4B3B,OAAO,CAAC,4BAA4B;IAmBpC,OAAO,CAAC,mBAAmB;IAyB3B,OAAO,CAAC,uBAAuB;CA+BhC"}

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

@@ -3,7 +3,18 @@
  * Evaluates documentation quality and completeness
  */
 import { BaseAssessor } from "./BaseAssessor.js";
+/**
+ * @deprecated Use DeveloperExperienceAssessor instead. Will be removed in v2.0.0.
+ */
 export class DocumentationAssessor extends BaseAssessor {
+    constructor(config) {
+        super(config);
+        this.logger.warn("DocumentationAssessor is deprecated. Use DeveloperExperienceAssessor instead. " +
+            "This module will be removed in v2.0.0.", {
+            module: "DocumentationAssessor",
+            replacement: "DeveloperExperienceAssessor",
+        });
+    }
     async assess(context) {
         this.log("Starting documentation assessment");
         const readmeContent = context.readmeContent || "";

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

@@ -13,7 +13,7 @@ export class ErrorHandlingAssessor extends BaseAssessor {
         const toolsToTest = this.selectToolsForTesting(context.tools);
         // Parallel tool testing with concurrency limit
         const concurrency = this.config.maxParallelTests ?? 5;
-        const limit = createConcurrencyLimit(concurrency);
+        const limit = createConcurrencyLimit(concurrency, this.logger);
         this.log(`Testing ${toolsToTest.length} tools for error handling with concurrency limit of ${concurrency}`);
         const allToolTests = await Promise.all(toolsToTest.map((tool) => limit(async () => {
             const toolTests = await this.testToolErrorHandling(tool, context.callTool);

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

@@ -1 +1 @@
-{"version":3,"file":"FunctionalityAssessor.d.ts","sourceRoot":"","sources":["../../../../src/services/assessment/modules/FunctionalityAssessor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,uBAAuB,EAGxB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAS9D,qBAAa,qBAAsB,SAAQ,YAAY;IACrD,OAAO,CAAC,cAAc,CAAwB;IAE9C;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAoCvB,MAAM,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,uBAAuB,CAAC;YAkI5D,QAAQ;IAgGtB,OAAO,CAAC,qBAAqB;IAmE7B,OAAO,CAAC,kBAAkB;IA4G1B;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,uBAAuB,CAe7C;IAEF;;;OAGG;IACH,OAAO,CAAC,mCAAmC;IAsF3C;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAWlB,iBAAiB,CAAC,MAAM,EAAE,GAAG,GAAG,OAAO;IAI9C,OAAO,CAAC,mBAAmB;CA+B5B"}
+{"version":3,"file":"FunctionalityAssessor.d.ts","sourceRoot":"","sources":["../../../../src/services/assessment/modules/FunctionalityAssessor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,uBAAuB,EAGxB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAU9D,qBAAa,qBAAsB,SAAQ,YAAY;IACrD,OAAO,CAAC,cAAc,CAAwB;IAE9C;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAoCvB,MAAM,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,uBAAuB,CAAC;YAmI5D,QAAQ;IAiGtB,OAAO,CAAC,qBAAqB;IAmE7B,OAAO,CAAC,kBAAkB;IA4G1B;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,uBAAuB,CAe7C;IAEF;;;OAGG;IACH,OAAO,CAAC,mCAAmC;IAsF3C;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAWlB,iBAAiB,CAAC,MAAM,EAAE,GAAG,GAAG,OAAO;IAI9C,OAAO,CAAC,mBAAmB;CA+B5B"}

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

@@ -9,6 +9,7 @@ import { ToolClassifier, ToolCategory } from "../ToolClassifier.js";
 import { TestDataGenerator } from "../TestDataGenerator.js";
 import { cleanParams } from "../../../utils/paramUtils.js";
 import { resolveRef, normalizeUnionType } from "../../../utils/schemaUtils.js";
+import { DEFAULT_PERFORMANCE_CONFIG } from "../config/performanceConfig.js";
 export class FunctionalityAssessor extends BaseAssessor {
     toolClassifier = new ToolClassifier();
     /**
@@ -46,14 +47,15 @@ export class FunctionalityAssessor extends BaseAssessor {
         const toolsToTest = this.selectToolsForTesting(context.tools);
         // Parallel tool testing with concurrency limit
         const concurrency = this.config.maxParallelTests ?? 5;
-        const limit = createConcurrencyLimit(concurrency);
+        const limit = createConcurrencyLimit(concurrency, this.logger);
         // Progress tracking for batched events
+        // Uses centralized PerformanceConfig values (Issue #37)
         const totalEstimate = toolsToTest.length;
         let completedTests = 0;
         let lastBatchTime = Date.now();
         const startTime = Date.now();
-        const BATCH_INTERVAL = 500;
-        const BATCH_SIZE = 5; // Smaller batch for functionality (fewer tests)
+        const BATCH_INTERVAL = DEFAULT_PERFORMANCE_CONFIG.batchFlushIntervalMs;
+        const BATCH_SIZE = DEFAULT_PERFORMANCE_CONFIG.functionalityBatchSize;
         let batchCount = 0;
         const emitProgressBatch = () => {
             if (context.onProgress) {
@@ -195,6 +197,7 @@ export class FunctionalityAssessor extends BaseAssessor {
             };
         }
         catch (error) {
+            this.logError(`Tool execution failed: ${tool.name}`, error);
             return {
                 toolName: tool.name,
                 tested: true,

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

@@ -5,6 +5,9 @@
 import { MCPSpecComplianceAssessment, AssessmentConfiguration } from "../../../lib/assessmentTypes.js";
 import { BaseAssessor } from "./BaseAssessor.js";
 import { AssessmentContext } from "../AssessmentOrchestrator.js";
+/**
+ * @deprecated Use ProtocolComplianceAssessor instead. Will be removed in v2.0.0.
+ */
 export declare class MCPSpecComplianceAssessor extends BaseAssessor {
     private ajv;
     constructor(config: AssessmentConfiguration);

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

@@ -1 +1 @@
-{"version":3,"file":"MCPSpecComplianceAssessor.d.ts","sourceRoot":"","sources":["../../../../src/services/assessment/modules/MCPSpecComplianceAssessor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,2BAA2B,EAM3B,uBAAuB,EAGxB,MAAM,uBAAuB,CAAC;AAO/B,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAE9D,qBAAa,yBAA0B,SAAQ,YAAY;IACzD,OAAO,CAAC,GAAG,CAAc;gBAEb,MAAM,EAAE,uBAAuB;IAK3C;;;OAGG;IACG,MAAM,CACV,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,2BAA2B,CAAC;IAmHvC;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAwB9B;;;OAGG;YACW,sBAAsB;IA6BpC;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAyB/B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAyC7B;;;OAGG;YACW,mBAAmB;IAsCjC;;OAEG;IACH,OAAO,CAAC,4BAA4B;IAiBpC;;;OAGG;IACH,OAAO,CAAC,2BAA2B;IA0FnC;;OAEG;IACH,OAAO,CAAC,yBAAyB;IAyFjC;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAsB/B;;OAEG;IACH,OAAO,CAAC,sBAAsB;IA4B9B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IA2C7B;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IAoF5B;;OAEG;IACH,OAAO,CAAC,yBAAyB;IAyBjC;;OAEG;IACH,OAAO,CAAC,6BAA6B;CA0DtC"}
+{"version":3,"file":"MCPSpecComplianceAssessor.d.ts","sourceRoot":"","sources":["../../../../src/services/assessment/modules/MCPSpecComplianceAssessor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,2BAA2B,EAM3B,uBAAuB,EAGxB,MAAM,uBAAuB,CAAC;AAO/B,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAE9D;;GAEG;AACH,qBAAa,yBAA0B,SAAQ,YAAY;IACzD,OAAO,CAAC,GAAG,CAAc;gBAEb,MAAM,EAAE,uBAAuB;IAa3C;;;OAGG;IACG,MAAM,CACV,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,2BAA2B,CAAC;IAmHvC;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAwB9B;;;OAGG;YACW,sBAAsB;IA6BpC;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAyB/B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IA0C7B;;;OAGG;YACW,mBAAmB;IAsCjC;;OAEG;IACH,OAAO,CAAC,4BAA4B;IAiBpC;;;OAGG;IACH,OAAO,CAAC,2BAA2B;IA0FnC;;OAEG;IACH,OAAO,CAAC,yBAAyB;IAyFjC;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAsB/B;;OAEG;IACH,OAAO,CAAC,sBAAsB;IA4B9B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IA2C7B;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IAoF5B;;OAEG;IACH,OAAO,CAAC,yBAAyB;IAyBjC;;OAEG;IACH,OAAO,CAAC,6BAA6B;CA0DtC"}

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

@@ -4,10 +4,18 @@
  */
 import Ajv from "ajv";
 import { BaseAssessor } from "./BaseAssessor.js";
+/**
+ * @deprecated Use ProtocolComplianceAssessor instead. Will be removed in v2.0.0.
+ */
 export class MCPSpecComplianceAssessor extends BaseAssessor {
     ajv;
     constructor(config) {
         super(config);
+        this.logger.warn("MCPSpecComplianceAssessor is deprecated. Use ProtocolComplianceAssessor instead. " +
+            "This module will be removed in v2.0.0.", {
+            module: "MCPSpecComplianceAssessor",
+            replacement: "ProtocolComplianceAssessor",
+        });
         this.ajv = new Ajv({ allErrors: true });
     }
     /**
@@ -198,7 +206,9 @@ export class MCPSpecComplianceAssessor extends BaseAssessor {
                         hasErrors = true;
                         const errorMsg = `${tool.name}: ${JSON.stringify(this.ajv.errors)}`;
                         errors.push(errorMsg);
-                        console.warn(`Invalid schema for tool ${tool.name}:`, this.ajv.errors);
+                        this.logger.warn(`Invalid schema for tool ${tool.name}`, {
+                            errors: this.ajv.errors,
+                        });
                     }
                 }
             }
@@ -210,7 +220,9 @@ export class MCPSpecComplianceAssessor extends BaseAssessor {
             };
         }
         catch (error) {
-            console.error("Schema compliance check failed:", error);
+            this.logger.error("Schema compliance check failed", {
+                error: String(error),
+            });
             return {
                 passed: false,
                 confidence: "low",