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

package/lib/services/assessment/config/sanitizationPatterns.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Sanitization Library Pattern Configuration
+ *
+ * Detects security libraries and sanitization practices in tool metadata/descriptions.
+ * Used by SanitizationDetector to reduce false positives when tools have proper
+ * input sanitization in place.
+ *
+ * @see Issue #56: Improve security analysis granularity
+ */
+/**
+ * Categories of sanitization approaches
+ */
+export type SanitizationCategory = "xss" | "html" | "sql" | "input" | "encoding" | "framework";
+/**
+ * Pattern definition for detecting a specific sanitization library
+ */
+export interface SanitizationLibraryPattern {
+    /** Library name for reporting */
+    name: string;
+    /** Regex patterns to detect this library */
+    patterns: RegExp[];
+    /** Type of sanitization this library provides */
+    category: SanitizationCategory;
+    /** Confidence boost when detected (15-25 points) */
+    confidenceBoost: number;
+    /** Languages this library is typically used with */
+    languageHint?: string[];
+}
+/**
+ * Known sanitization libraries with detection patterns
+ *
+ * Detection is conservative - patterns match explicit mentions of libraries
+ * rather than generic terms that could have other meanings.
+ */
+export declare const SANITIZATION_LIBRARY_PATTERNS: SanitizationLibraryPattern[];
+/**
+ * Generic sanitization keyword patterns
+ *
+ * These are less specific than library patterns and provide lower confidence boost.
+ * Used when no specific library is detected but sanitization is mentioned.
+ */
+export declare const GENERIC_SANITIZATION_KEYWORDS: RegExp[];
+/**
+ * Response-time sanitization indicators
+ *
+ * Patterns that indicate sanitization was applied to the response.
+ * These provide evidence that input was processed safely.
+ */
+export declare const RESPONSE_SANITIZATION_INDICATORS: RegExp[];
+/**
+ * Confidence boost values for different detection types
+ */
+export declare const CONFIDENCE_BOOSTS: {
+    /** Specific library detected (e.g., DOMPurify) */
+    readonly SPECIFIC_LIBRARY: 25;
+    /** Generic sanitization keyword detected */
+    readonly GENERIC_KEYWORD: 8;
+    /** Response-time sanitization evidence */
+    readonly RESPONSE_EVIDENCE: 10;
+    /** Maximum total adjustment (cap) */
+    readonly MAX_ADJUSTMENT: 50;
+};
+//# sourceMappingURL=sanitizationPatterns.d.ts.map

package/lib/services/assessment/config/sanitizationPatterns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitizationPatterns.d.ts","sourceRoot":"","sources":["../../../../src/services/assessment/config/sanitizationPatterns.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAC5B,KAAK,GACL,MAAM,GACN,KAAK,GACL,OAAO,GACP,UAAU,GACV,WAAW,CAAC;AAEhB;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,iDAAiD;IACjD,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,oDAAoD;IACpD,eAAe,EAAE,MAAM,CAAC;IACxB,oDAAoD;IACpD,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B,EAAE,0BAA0B,EAkKrE,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B,EAAE,MAAM,EAWjD,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gCAAgC,EAAE,MAAM,EAWpD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,iBAAiB;IAC5B,kDAAkD;;IAElD,4CAA4C;;IAE5C,0CAA0C;;IAE1C,qCAAqC;;CAE7B,CAAC"}

package/lib/services/assessment/config/sanitizationPatterns.js

@@ -0,0 +1,223 @@
+/**
+ * Sanitization Library Pattern Configuration
+ *
+ * Detects security libraries and sanitization practices in tool metadata/descriptions.
+ * Used by SanitizationDetector to reduce false positives when tools have proper
+ * input sanitization in place.
+ *
+ * @see Issue #56: Improve security analysis granularity
+ */
+/**
+ * Known sanitization libraries with detection patterns
+ *
+ * Detection is conservative - patterns match explicit mentions of libraries
+ * rather than generic terms that could have other meanings.
+ */
+export const SANITIZATION_LIBRARY_PATTERNS = [
+    // XSS Prevention Libraries
+    {
+        name: "DOMPurify",
+        patterns: [/\bDOMPurify\b/i, /\bdom[\-_]?purify\b/i],
+        category: "xss",
+        confidenceBoost: 25,
+        languageHint: ["javascript", "typescript"],
+    },
+    {
+        name: "xss",
+        patterns: [
+            /\bxss\s*\(/i,
+            /require\s*\(\s*['"]xss['"]\s*\)/i,
+            /import.*from\s+['"]xss['"]/i,
+            /xss\s+library/i,
+        ],
+        category: "xss",
+        confidenceBoost: 25,
+        languageHint: ["javascript", "typescript"],
+    },
+    {
+        name: "bleach",
+        patterns: [/\bbleach\b/i, /bleach\.clean/i, /import\s+bleach/i],
+        category: "xss",
+        confidenceBoost: 25,
+        languageHint: ["python"],
+    },
+    // HTML Sanitization
+    {
+        name: "sanitize-html",
+        patterns: [
+            /\bsanitize[\-_]?html\b/i,
+            /sanitizeHtml\s*\(/i,
+            /require\s*\(\s*['"]sanitize-html['"]\s*\)/i,
+        ],
+        category: "html",
+        confidenceBoost: 20,
+        languageHint: ["javascript", "typescript"],
+    },
+    {
+        name: "escape-html",
+        patterns: [
+            /\bescape[\-_]?html\b/i,
+            /escapeHtml\s*\(/i,
+            /require\s*\(\s*['"]escape-html['"]\s*\)/i,
+        ],
+        category: "encoding",
+        confidenceBoost: 15,
+        languageHint: ["javascript", "typescript"],
+    },
+    {
+        name: "he",
+        patterns: [
+            /\bhe\.encode/i,
+            /\bhe\.escape/i,
+            /require\s*\(\s*['"]he['"]\s*\)/i,
+        ],
+        category: "encoding",
+        confidenceBoost: 15,
+        languageHint: ["javascript", "typescript"],
+    },
+    // Input Validation Libraries
+    {
+        name: "validator",
+        patterns: [
+            /validator\.js/i,
+            /\bvalidatorjs\b/i,
+            /validator\.(isEmail|escape|sanitize|isURL|isAlphanumeric)/i,
+            /require\s*\(\s*['"]validator['"]\s*\)/i,
+        ],
+        category: "input",
+        confidenceBoost: 20,
+        languageHint: ["javascript", "typescript"],
+    },
+    {
+        name: "Zod",
+        patterns: [
+            /\bz\.string\s*\(\)/i,
+            /\bz\.object\s*\(/i,
+            /\bzod\b/i,
+            /\.safeParse\s*\(/i,
+            /import.*from\s+['"]zod['"]/i,
+        ],
+        category: "input",
+        confidenceBoost: 15,
+        languageHint: ["typescript"],
+    },
+    {
+        name: "Joi",
+        patterns: [
+            /\bJoi\b/i,
+            /Joi\.string\s*\(\)/i,
+            /Joi\.object\s*\(/i,
+            /\.validate\s*\(/i,
+            /require\s*\(\s*['"]joi['"]\s*\)/i,
+        ],
+        category: "input",
+        confidenceBoost: 15,
+        languageHint: ["javascript", "typescript"],
+    },
+    {
+        name: "yup",
+        patterns: [
+            /\byup\b/i,
+            /yup\.string\s*\(\)/i,
+            /yup\.object\s*\(/i,
+            /import.*from\s+['"]yup['"]/i,
+        ],
+        category: "input",
+        confidenceBoost: 15,
+        languageHint: ["javascript", "typescript"],
+    },
+    {
+        name: "pydantic",
+        patterns: [
+            /\bpydantic\b/i,
+            /from\s+pydantic\s+import/i,
+            /BaseModel/i,
+            /Field\s*\(/i,
+        ],
+        category: "input",
+        confidenceBoost: 15,
+        languageHint: ["python"],
+    },
+    // SQL Injection Prevention
+    {
+        name: "parameterized-queries",
+        patterns: [
+            /prepared[\s_]?statement/i,
+            /parameterized[\s_]?quer/i,
+            /\$\d+\s/i, // PostgreSQL style $1, $2
+            /:\w+\s/i, // Named parameters :name
+            /\?\s/i, // Positional parameters ?
+        ],
+        category: "sql",
+        confidenceBoost: 20,
+        languageHint: ["sql"],
+    },
+    // Framework-level Protection
+    {
+        name: "helmet",
+        patterns: [
+            /\bhelmet\b/i,
+            /helmet\s*\(\)/i,
+            /require\s*\(\s*['"]helmet['"]\s*\)/i,
+        ],
+        category: "framework",
+        confidenceBoost: 10,
+        languageHint: ["javascript", "typescript"],
+    },
+    {
+        name: "django-csrf",
+        patterns: [/csrf_token/i, /CsrfViewMiddleware/i, /@csrf_protect/i],
+        category: "framework",
+        confidenceBoost: 10,
+        languageHint: ["python"],
+    },
+];
+/**
+ * Generic sanitization keyword patterns
+ *
+ * These are less specific than library patterns and provide lower confidence boost.
+ * Used when no specific library is detected but sanitization is mentioned.
+ */
+export const GENERIC_SANITIZATION_KEYWORDS = [
+    /\bsanitiz(e|ed|es|ing|ation)\b/i,
+    /\bescap(e|ed|es|ing)\b/i,
+    /\bencod(e|ed|es|ing)\b/i,
+    /\bvalidat(e|ed|es|ing|ion)\b/i,
+    /\bfilter(ed|s|ing)?\b/i,
+    /\bclean(ed|s|ing)?\b/i,
+    /\bpurif(y|ied|ies|ying)\b/i,
+    /\bnormaliz(e|ed|es|ing)\b/i,
+    /\bstrip(ped|s|ping)?\b/i,
+    /\btrim(med|s|ming)?\b/i,
+];
+/**
+ * Response-time sanitization indicators
+ *
+ * Patterns that indicate sanitization was applied to the response.
+ * These provide evidence that input was processed safely.
+ */
+export const RESPONSE_SANITIZATION_INDICATORS = [
+    /\[sanitized\]/i,
+    /\[filtered\]/i,
+    /\[redacted\]/i,
+    /\[removed\]/i,
+    /\[cleaned\]/i,
+    /\[escaped\]/i,
+    /input.*sanitized/i,
+    /content.*filtered/i,
+    /value.*cleaned/i,
+    /data.*validated/i,
+];
+/**
+ * Confidence boost values for different detection types
+ */
+export const CONFIDENCE_BOOSTS = {
+    /** Specific library detected (e.g., DOMPurify) */
+    SPECIFIC_LIBRARY: 25,
+    /** Generic sanitization keyword detected */
+    GENERIC_KEYWORD: 8,
+    /** Response-time sanitization evidence */
+    RESPONSE_EVIDENCE: 10,
+    /** Maximum total adjustment (cap) */
+    MAX_ADJUSTMENT: 50,
+};

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

@@ -12,6 +12,7 @@
  */
 import type { Tool } from "@modelcontextprotocol/sdk/types.js";
 import type { AUPCategory } from "../../../lib/assessmentTypes.js";
+import { Logger } from "./logger.js";
 /**
  * Response from Claude Code execution
  */
@@ -103,7 +104,8 @@ export declare const FULL_CLAUDE_CODE_CONFIG: ClaudeCodeBridgeConfig;
 export declare class ClaudeCodeBridge {
     private config;
     private isAvailable;
-    constructor(config: ClaudeCodeBridgeConfig);
+    private logger?;
+    constructor(config: ClaudeCodeBridgeConfig, logger?: Logger);
     /**
      * Check if a specific feature is enabled
      * Note: annotationInference is an alias for behaviorInference

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

@@ -1 +1 @@
-{"version":3,"file":"claudeCodeBridge.d.ts","sourceRoot":"","sources":["../../../../src/services/assessment/lib/claudeCodeBridge.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"claudeCodeBridge.d.ts","sourceRoot":"","sources":["../../../../src/services/assessment/lib/claudeCodeBridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oCAAoC,CAAC;AAC/D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAElC;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE;QACR,yBAAyB,CAAC,EAAE,OAAO,CAAC;QACpC,mBAAmB,CAAC,EAAE,OAAO,CAAC;QAC9B,iBAAiB,CAAC,EAAE,OAAO,CAAC;QAC5B,mBAAmB,CAAC,EAAE,OAAO,CAAC;QAC9B,uBAAuB,CAAC,EAAE,OAAO,CAAC;QAClC,oBAAoB,CAAC,EAAE,OAAO,CAAC;KAChC,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,WAAW,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,WAAW,EAAE,OAAO,CAAC;IACrB,oBAAoB,EAAE,OAAO,CAAC;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,WAAW,CAAC;IACtB,eAAe,EAAE,OAAO,GAAG,iBAAiB,GAAG,OAAO,CAAC;IACvD,cAAc,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,gBAAgB,EAAE,OAAO,CAAC;IAC1B,mBAAmB,EAAE,OAAO,CAAC;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,oBAAoB,EAAE;QACpB,YAAY,CAAC,EAAE,OAAO,CAAC;QACvB,eAAe,CAAC,EAAE,OAAO,CAAC;QAC1B,cAAc,CAAC,EAAE,OAAO,CAAC;KAC1B,CAAC;IACF,oBAAoB,EAAE,OAAO,CAAC;IAC9B,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,KAAK,CAAC;QACf,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAChC,gBAAgB,EAAE,MAAM,CAAC;QACzB,QAAQ,EAAE,YAAY,GAAG,WAAW,GAAG,UAAU,GAAG,YAAY,CAAC;KAClE,CAAC,CAAC;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,eAAO,MAAM,0BAA0B,EAAE,sBAYxC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,uBAAuB,EAAE,sBAYrC,CAAC;AAEF;;;GAGG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAyB;IACvC,OAAO,CAAC,WAAW,CAAkB;IACrC,OAAO,CAAC,MAAM,CAAC,CAAS;gBAEZ,MAAM,EAAE,sBAAsB,EAAE,MAAM,CAAC,EAAE,MAAM;IAU3D;;;OAGG;IACH,gBAAgB,CAAC,OAAO,EAAE,MAAM,sBAAsB,CAAC,UAAU,CAAC,GAAG,OAAO;IAgB5E;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAS/B;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IA8B5B;;OAEG;YACW,gBAAgB;IAwB9B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAqBzB;;;;OAIG;IACG,mBAAmB,CACvB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,yBAAyB,GAAG,IAAI,CAAC;IA2C5C;;OAEG;IACG,iBAAiB,CACrB,IAAI,EAAE,IAAI,EACV,kBAAkB,CAAC,EAAE;QACnB,YAAY,CAAC,EAAE,OAAO,CAAC;QACvB,eAAe,CAAC,EAAE,OAAO,CAAC;QAC1B,cAAc,CAAC,EAAE,OAAO,CAAC;KAC1B,GACA,OAAO,CAAC,uBAAuB,GAAG,IAAI,CAAC;IAgD1C;;OAEG;IACG,qBAAqB,CACzB,IAAI,EAAE,IAAI,EACV,iBAAiB,EAAE,MAAM,GACxB,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IAuCvC;;;OAGG;IACG,sBAAsB,CAC1B,IAAI,EAAE,IAAI,GACT,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,IAAI,CAAC;IAqC5C;;OAEG;IACG,mBAAmB,CACvB,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC;QACT,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,EAAE,CAAC;QACjB,WAAW,EAAE,MAAM,EAAE,CAAC;KACvB,GAAG,IAAI,CAAC;CA0CV"}

package/lib/services/assessment/lib/claudeCodeBridge.js

@@ -50,11 +50,13 @@ export const FULL_CLAUDE_CODE_CONFIG = {
 export class ClaudeCodeBridge {
     config;
     isAvailable = false;
-    constructor(config) {
+    logger;
+    constructor(config, logger) {
         this.config = config;
+        this.logger = logger;
         this.isAvailable = this.checkClaudeAvailability();
         if (!this.isAvailable) {
-            console.warn("[ClaudeCodeBridge] Claude CLI not available - features will be disabled");
+            this.logger?.warn("Claude CLI not available - features will be disabled");
         }
     }
     /**
@@ -151,7 +153,7 @@ export class ClaudeCodeBridge {
             return JSON.parse(jsonStr);
         }
         catch {
-            console.warn("[ClaudeCodeBridge] Failed to parse JSON response");
+            this.logger?.warn("Failed to parse JSON response");
             return null;
         }
     }

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

@@ -2,6 +2,7 @@
  * Simple concurrency limiter for parallel async operations
  * Provides the same interface as p-limit but is CJS-compatible
  */
+import { Logger } from "./logger.js";
 /**
  * Warning threshold for queue depth monitoring.
  * If queue exceeds this size, a warning is emitted to help diagnose
@@ -12,14 +13,17 @@
  *
  * Threshold of 10,000 provides ~146% headroom to accommodate larger
  * tool sets while catching true runaway scenarios.
+ *
+ * @see PerformanceConfig.queueWarningThreshold (Issue #37)
  */
-export declare const QUEUE_WARNING_THRESHOLD = 10000;
+export declare const QUEUE_WARNING_THRESHOLD: number;
 export type LimitFunction = <T>(fn: () => Promise<T>) => Promise<T>;
 /**
  * Creates a concurrency limiter that allows only a specified number
  * of async operations to run simultaneously
  *
  * @param concurrency - Maximum number of concurrent operations
+ * @param logger - Optional logger instance for queue depth warnings
  * @returns A function that wraps async operations with the concurrency limit
  *
  * @example
@@ -28,5 +32,5 @@ export type LimitFunction = <T>(fn: () => Promise<T>) => Promise<T>;
  *   items.map(item => limit(() => processItem(item)))
  * );
  */
-export declare function createConcurrencyLimit(concurrency: number): LimitFunction;
+export declare function createConcurrencyLimit(concurrency: number, logger?: Logger): LimitFunction;
 //# sourceMappingURL=concurrencyLimit.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"concurrencyLimit.d.ts","sourceRoot":"","sources":["../../../../src/services/assessment/lib/concurrencyLimit.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,uBAAuB,QAAQ,CAAC;AAE7C,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;AAEpE;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,CAuDzE"}
+{"version":3,"file":"concurrencyLimit.d.ts","sourceRoot":"","sources":["../../../../src/services/assessment/lib/concurrencyLimit.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAGlC;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,uBAAuB,QACc,CAAC;AAEnD,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;AAEpE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,MAAM,EACnB,MAAM,CAAC,EAAE,MAAM,GACd,aAAa,CAwDf"}

package/lib/services/assessment/lib/concurrencyLimit.js

@@ -2,6 +2,7 @@
  * Simple concurrency limiter for parallel async operations
  * Provides the same interface as p-limit but is CJS-compatible
  */
+import { DEFAULT_PERFORMANCE_CONFIG } from "../config/performanceConfig.js";
 /**
  * Warning threshold for queue depth monitoring.
  * If queue exceeds this size, a warning is emitted to help diagnose
@@ -12,13 +13,16 @@
  *
  * Threshold of 10,000 provides ~146% headroom to accommodate larger
  * tool sets while catching true runaway scenarios.
+ *
+ * @see PerformanceConfig.queueWarningThreshold (Issue #37)
  */
-export const QUEUE_WARNING_THRESHOLD = 10000;
+export const QUEUE_WARNING_THRESHOLD = DEFAULT_PERFORMANCE_CONFIG.queueWarningThreshold;
 /**
  * Creates a concurrency limiter that allows only a specified number
  * of async operations to run simultaneously
  *
  * @param concurrency - Maximum number of concurrent operations
+ * @param logger - Optional logger instance for queue depth warnings
  * @returns A function that wraps async operations with the concurrency limit
  *
  * @example
@@ -27,7 +31,7 @@ export const QUEUE_WARNING_THRESHOLD = 10000;
  *   items.map(item => limit(() => processItem(item)))
  * );
  */
-export function createConcurrencyLimit(concurrency) {
+export function createConcurrencyLimit(concurrency, logger) {
     if (concurrency < 1) {
         throw new Error("Concurrency must be at least 1");
     }
@@ -62,10 +66,13 @@ export function createConcurrencyLimit(concurrency) {
             // Only warn once per limiter instance to avoid log spam
             if (queue.length > QUEUE_WARNING_THRESHOLD && !hasWarned) {
                 hasWarned = true;
-                console.warn(`[concurrencyLimit] Queue depth: ${queue.length} ` +
-                    `(threshold: ${QUEUE_WARNING_THRESHOLD}). ` +
-                    `Active: ${activeCount}/${concurrency}. ` +
-                    `This may indicate a slow/stalled server.`);
+                logger?.warn("Queue depth exceeded threshold", {
+                    queueDepth: queue.length,
+                    threshold: QUEUE_WARNING_THRESHOLD,
+                    activeCount,
+                    concurrency,
+                    message: "This may indicate a slow/stalled server",
+                });
             }
             next();
         });

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

@@ -0,0 +1,90 @@
+/**
+ * Assessment Error Types
+ *
+ * Provides standardized error handling across all assessment modules.
+ * See docs/ERROR_HANDLING_CONVENTIONS.md for usage guidelines.
+ */
+/**
+ * Error categories for classification and debugging
+ */
+export declare enum ErrorCategory {
+    /** Network connectivity issues (ECONNREFUSED, DNS failures, etc.) */
+    CONNECTION = "CONNECTION",
+    /** MCP protocol violations or unexpected responses */
+    PROTOCOL = "PROTOCOL",
+    /** Input validation failures (invalid parameters, missing fields) */
+    VALIDATION = "VALIDATION",
+    /** Operation exceeded time limit */
+    TIMEOUT = "TIMEOUT",
+    /** JSON or data parsing failures */
+    PARSE = "PARSE",
+    /** Unclassified errors */
+    UNKNOWN = "UNKNOWN"
+}
+/**
+ * Custom error class for assessment operations
+ *
+ * @example
+ * throw new AssessmentError(
+ *   'Failed to connect to MCP server',
+ *   ErrorCategory.CONNECTION,
+ *   false, // not recoverable
+ *   { url: 'http://localhost:3000', attempt: 3 }
+ * );
+ */
+export declare class AssessmentError extends Error {
+    readonly code: ErrorCategory;
+    readonly recoverable: boolean;
+    readonly context?: Record<string, unknown>;
+    constructor(message: string, code: ErrorCategory, recoverable?: boolean, context?: Record<string, unknown>);
+    /**
+     * Create a structured object for serialization
+     */
+    toJSON(): ErrorInfo;
+}
+/**
+ * Structured error information for result objects
+ */
+export interface ErrorInfo {
+    /** Human-readable error message */
+    message: string;
+    /** Error category for classification */
+    code: ErrorCategory;
+    /** Whether the operation can be retried */
+    recoverable: boolean;
+    /** Stack trace (optional, for debugging) */
+    stack?: string;
+    /** Additional context about the error */
+    context?: Record<string, unknown>;
+}
+/**
+ * Interface for result objects that may contain errors
+ *
+ * @example
+ * interface ToolTestResult extends ErrorResult {
+ *   toolName: string;
+ *   passed: boolean;
+ * }
+ */
+export interface ErrorResult {
+    error?: ErrorInfo;
+}
+/**
+ * Type guard to check if a value is an AssessmentError
+ */
+export declare function isAssessmentError(error: unknown): error is AssessmentError;
+/**
+ * Categorize an error based on its message content
+ *
+ * @param error - The error to categorize
+ * @returns The appropriate ErrorCategory
+ */
+export declare function categorizeError(error: unknown): ErrorCategory;
+/**
+ * Extract error message from various error types
+ *
+ * @param error - The error to extract message from
+ * @returns A string error message
+ */
+export declare function extractErrorMessage(error: unknown): string;
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../../src/services/assessment/lib/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,oBAAY,aAAa;IACvB,qEAAqE;IACrE,UAAU,eAAe;IACzB,sDAAsD;IACtD,QAAQ,aAAa;IACrB,qEAAqE;IACrE,UAAU,eAAe;IACzB,oCAAoC;IACpC,OAAO,YAAY;IACnB,oCAAoC;IACpC,KAAK,UAAU;IACf,0BAA0B;IAC1B,OAAO,YAAY;CACpB;AAED;;;;;;;;;;GAUG;AACH,qBAAa,eAAgB,SAAQ,KAAK;aAGtB,IAAI,EAAE,aAAa;aACnB,WAAW,EAAE,OAAO;aACpB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;gBAHjD,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,aAAa,EACnB,WAAW,GAAE,OAAc,EAC3B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAUnD;;OAEG;IACH,MAAM,IAAI,SAAS;CASpB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,mCAAmC;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,IAAI,EAAE,aAAa,CAAC;IACpB,2CAA2C;IAC3C,WAAW,EAAE,OAAO,CAAC;IACrB,4CAA4C;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,WAAW;IAC1B,KAAK,CAAC,EAAE,SAAS,CAAC;CACnB;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAE1E;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,aAAa,CAsC7D;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAwB1D"}

package/lib/services/assessment/lib/errors.js

@@ -0,0 +1,136 @@
+/**
+ * Assessment Error Types
+ *
+ * Provides standardized error handling across all assessment modules.
+ * See docs/ERROR_HANDLING_CONVENTIONS.md for usage guidelines.
+ */
+/**
+ * Error categories for classification and debugging
+ */
+export var ErrorCategory;
+(function (ErrorCategory) {
+    /** Network connectivity issues (ECONNREFUSED, DNS failures, etc.) */
+    ErrorCategory["CONNECTION"] = "CONNECTION";
+    /** MCP protocol violations or unexpected responses */
+    ErrorCategory["PROTOCOL"] = "PROTOCOL";
+    /** Input validation failures (invalid parameters, missing fields) */
+    ErrorCategory["VALIDATION"] = "VALIDATION";
+    /** Operation exceeded time limit */
+    ErrorCategory["TIMEOUT"] = "TIMEOUT";
+    /** JSON or data parsing failures */
+    ErrorCategory["PARSE"] = "PARSE";
+    /** Unclassified errors */
+    ErrorCategory["UNKNOWN"] = "UNKNOWN";
+})(ErrorCategory || (ErrorCategory = {}));
+/**
+ * Custom error class for assessment operations
+ *
+ * @example
+ * throw new AssessmentError(
+ *   'Failed to connect to MCP server',
+ *   ErrorCategory.CONNECTION,
+ *   false, // not recoverable
+ *   { url: 'http://localhost:3000', attempt: 3 }
+ * );
+ */
+export class AssessmentError extends Error {
+    code;
+    recoverable;
+    context;
+    constructor(message, code, recoverable = true, context) {
+        super(message);
+        this.code = code;
+        this.recoverable = recoverable;
+        this.context = context;
+        this.name = "AssessmentError";
+        // Maintains proper stack trace in V8 environments
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, AssessmentError);
+        }
+    }
+    /**
+     * Create a structured object for serialization
+     */
+    toJSON() {
+        return {
+            message: this.message,
+            code: this.code,
+            recoverable: this.recoverable,
+            stack: this.stack,
+            context: this.context,
+        };
+    }
+}
+/**
+ * Type guard to check if a value is an AssessmentError
+ */
+export function isAssessmentError(error) {
+    return error instanceof AssessmentError;
+}
+/**
+ * Categorize an error based on its message content
+ *
+ * @param error - The error to categorize
+ * @returns The appropriate ErrorCategory
+ */
+export function categorizeError(error) {
+    const message = extractErrorMessage(error).toLowerCase();
+    if (message.includes("timeout") || message.includes("timed out")) {
+        return ErrorCategory.TIMEOUT;
+    }
+    if (message.includes("connection") ||
+        message.includes("econnrefused") ||
+        message.includes("enotfound") ||
+        message.includes("network")) {
+        return ErrorCategory.CONNECTION;
+    }
+    if (message.includes("parse") ||
+        message.includes("json") ||
+        message.includes("syntax")) {
+        return ErrorCategory.PARSE;
+    }
+    if (message.includes("protocol") ||
+        message.includes("mcp") ||
+        message.includes("invalid response")) {
+        return ErrorCategory.PROTOCOL;
+    }
+    if (message.includes("invalid") ||
+        message.includes("required") ||
+        message.includes("missing") ||
+        message.includes("validation")) {
+        return ErrorCategory.VALIDATION;
+    }
+    return ErrorCategory.UNKNOWN;
+}
+/**
+ * Extract error message from various error types
+ *
+ * @param error - The error to extract message from
+ * @returns A string error message
+ */
+export function extractErrorMessage(error) {
+    if (typeof error === "string") {
+        return error;
+    }
+    if (error instanceof Error) {
+        return error.message;
+    }
+    if (error && typeof error === "object") {
+        const err = error;
+        if (typeof err.message === "string") {
+            return err.message;
+        }
+        if (typeof err.error === "string") {
+            return err.error;
+        }
+        if (err.error && typeof err.error === "object") {
+            return extractErrorMessage(err.error);
+        }
+    }
+    try {
+        return JSON.stringify(error);
+    }
+    catch {
+        return String(error);
+    }
+}