agentic-qe 3.15.2 → 3.15.4

package/dist/shared/llm/providers/gemini.js

@@ -12,6 +12,7 @@ import { createLLMError, } from '../interfaces.js';
 import { TokenMetricsCollector } from '../../../learning/token-tracker.js';
 import { toError } from '../../error-utils.js';
 import { backoffDelay } from '../retry.js';
+import { fetchWithResponseDeadline } from './response-deadline.js';
 import { safeJsonParse } from '../../safe-json.js';
 /**
  * Default Gemini configuration
@@ -246,7 +247,7 @@ export class GeminiProvider {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
             body: JSON.stringify(body),
-        }, options?.timeoutMs ?? this.config.timeoutMs ?? 60000);
+        }, options?.timeoutMs ?? this.config.timeoutMs ?? 60000, 'idle');
         if (!response.ok) {
             const errorData = await response.json().catch(() => ({
                 error: { message: 'Unknown error', code: 0, status: 'UNKNOWN' },
@@ -304,6 +305,8 @@ export class GeminiProvider {
             }
         }
         finally {
+            // Returning early from the generator must also release its request deadline.
+            await reader.cancel().catch(() => { });
             reader.releaseLock();
         }
         const latencyMs = Date.now() - start;
@@ -574,28 +577,11 @@ export class GeminiProvider {
     /**
      * Fetch with timeout
      */
-    async fetchWithTimeout(url, options, timeoutMs) {
-        const controller = new AbortController();
-        const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
-        try {
-            const response = await fetch(url, {
-                ...options,
-                signal: controller.signal,
-            });
-            return response;
-        }
-        catch (error) {
-            if (error instanceof Error && error.name === 'AbortError') {
-                throw createLLMError('Request timed out', 'TIMEOUT', {
-                    provider: 'gemini',
-                    retryable: true,
-                });
-            }
-            throw error;
-        }
-        finally {
-            clearTimeout(timeoutId);
-        }
+    async fetchWithTimeout(url, options, timeoutMs, bodyDeadline = 'absolute') {
+        return fetchWithResponseDeadline(url, options, timeoutMs, () => createLLMError('Request timed out', 'TIMEOUT', {
+            provider: 'gemini',
+            retryable: true,
+        }), bodyDeadline);
     }
     /**
      * Fetch with retry logic

package/dist/shared/llm/providers/ollama.js

@@ -5,6 +5,7 @@
  * Local LLM provider using Ollama for fast iteration and zero-cost development.
  * Supports Llama, Mistral, CodeLlama, and other local models.
  */
+import { fetchWithResponseDeadline } from './response-deadline.js';
 import { createLLMError, } from '../interfaces.js';
 import { CostTracker } from '../cost-tracker.js';
 import { TokenMetricsCollector } from '../../../learning/token-tracker.js';
@@ -410,27 +411,10 @@ export class OllamaProvider {
      * Fetch with timeout
      */
     async fetchWithTimeout(url, options, timeoutMs) {
-        const controller = new AbortController();
-        const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
-        try {
-            const response = await fetch(url, {
-                ...options,
-                signal: controller.signal,
-            });
-            return response;
-        }
-        catch (error) {
-            if (error instanceof Error && error.name === 'AbortError') {
-                throw createLLMError('Request timed out', 'TIMEOUT', {
-                    provider: 'ollama',
-                    retryable: true,
-                });
-            }
-            throw error;
-        }
-        finally {
-            clearTimeout(timeoutId);
-        }
+        return fetchWithResponseDeadline(url, options, timeoutMs, () => createLLMError('Request timed out', 'TIMEOUT', {
+            provider: 'ollama',
+            retryable: true,
+        }));
     }
 }
 //# sourceMappingURL=ollama.js.map

package/dist/shared/llm/providers/openai.js

@@ -11,6 +11,7 @@ import { applyOpenAIParams } from '../openai-params.js';
 import { TokenMetricsCollector } from '../../../learning/token-tracker.js';
 import { toError } from '../../error-utils.js';
 import { backoffDelay } from '../retry.js';
+import { fetchWithResponseDeadline } from './response-deadline.js';
 /**
  * Default OpenAI configuration
  */
@@ -378,27 +379,10 @@ export class OpenAIProvider {
      * Fetch with timeout
      */
     async fetchWithTimeout(url, options, timeoutMs) {
-        const controller = new AbortController();
-        const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
-        try {
-            const response = await fetch(url, {
-                ...options,
-                signal: controller.signal,
-            });
-            return response;
-        }
-        catch (error) {
-            if (error instanceof Error && error.name === 'AbortError') {
-                throw createLLMError('Request timed out', 'TIMEOUT', {
-                    provider: 'openai',
-                    retryable: true,
-                });
-            }
-            throw error;
-        }
-        finally {
-            clearTimeout(timeoutId);
-        }
+        return fetchWithResponseDeadline(url, options, timeoutMs, () => createLLMError('Request timed out', 'TIMEOUT', {
+            provider: 'openai',
+            retryable: true,
+        }));
     }
     /**
      * Fetch with retry logic

package/dist/shared/llm/providers/openrouter.js

@@ -13,6 +13,7 @@ import { createLLMError, } from '../interfaces.js';
 import { TokenMetricsCollector } from '../../../learning/token-tracker.js';
 import { toError } from '../../error-utils.js';
 import { backoffDelay } from '../retry.js';
+import { fetchWithResponseDeadline } from './response-deadline.js';
 import { safeJsonParse } from '../../safe-json.js';
 import { resolveModelPricing } from '../cost-tracker.js';
 /**
@@ -273,7 +274,7 @@ export class OpenRouterProvider {
             method: 'POST',
             headers: this.getHeaders(),
             body: JSON.stringify(body),
-        }, options?.timeoutMs ?? this.config.timeoutMs ?? 60000);
+        }, options?.timeoutMs ?? this.config.timeoutMs ?? 60000, 'idle');
         if (!response.ok) {
             const errorData = await response.json().catch(() => ({
                 error: { message: 'Unknown error', type: 'unknown', code: null },
@@ -327,6 +328,8 @@ export class OpenRouterProvider {
             }
         }
         finally {
+            // Returning early from the generator must also release its request deadline.
+            await reader.cancel().catch(() => { });
             reader.releaseLock();
         }
         const latencyMs = Date.now() - start;
@@ -620,28 +623,11 @@ export class OpenRouterProvider {
     /**
      * Fetch with timeout
      */
-    async fetchWithTimeout(url, options, timeoutMs) {
-        const controller = new AbortController();
-        const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
-        try {
-            const response = await fetch(url, {
-                ...options,
-                signal: controller.signal,
-            });
-            return response;
-        }
-        catch (error) {
-            if (error instanceof Error && error.name === 'AbortError') {
-                throw createLLMError('Request timed out', 'TIMEOUT', {
-                    provider: 'openrouter',
-                    retryable: true,
-                });
-            }
-            throw error;
-        }
-        finally {
-            clearTimeout(timeoutId);
-        }
+    async fetchWithTimeout(url, options, timeoutMs, bodyDeadline = 'absolute') {
+        return fetchWithResponseDeadline(url, options, timeoutMs, () => createLLMError('Request timed out', 'TIMEOUT', {
+            provider: 'openrouter',
+            retryable: true,
+        }), bodyDeadline);
     }
     /**
      * Fetch with retry logic

package/dist/shared/llm/providers/response-deadline.d.ts

@@ -0,0 +1,3 @@
+/** Bound headers and bodies; streaming callers may use an idle body deadline. */
+export declare function fetchWithResponseDeadline(url: string, options: RequestInit, timeoutMs: number, timeoutError: () => Error, bodyDeadline?: 'absolute' | 'idle'): Promise<Response>;
+//# sourceMappingURL=response-deadline.d.ts.map

package/dist/shared/llm/providers/response-deadline.js

@@ -0,0 +1,100 @@
+/** Bound headers and bodies; streaming callers may use an idle body deadline. */
+export async function fetchWithResponseDeadline(url, options, timeoutMs, timeoutError, bodyDeadline = 'absolute') {
+    const abort = new AbortController();
+    let expired = false;
+    let expireBody;
+    const expire = () => {
+        expired = true;
+        const error = timeoutError();
+        expireBody?.(error);
+        abort.abort(error);
+    };
+    let timer = setTimeout(expire, timeoutMs);
+    const resetIdleDeadline = () => {
+        if (bodyDeadline !== 'idle')
+            return;
+        clearTimeout(timer);
+        timer = setTimeout(expire, timeoutMs);
+        timer.unref?.();
+    };
+    // A status-only caller must not keep a process alive until its deadline.
+    timer.unref?.();
+    try {
+        const response = await fetch(url, { ...options, signal: abort.signal });
+        if (!response.body) {
+            clearTimeout(timer);
+            return response;
+        }
+        resetIdleDeadline();
+        const reader = response.body.getReader();
+        let finished = false;
+        const finish = () => {
+            finished = true;
+            clearTimeout(timer);
+        };
+        const body = new ReadableStream({
+            start(controller) {
+                expireBody = error => {
+                    if (finished)
+                        return;
+                    finish();
+                    controller.error(error);
+                    // Cancel also settles any pending read before releasing its lock.
+                    void reader.cancel(error).catch(() => { }).finally(() => reader.releaseLock());
+                };
+            },
+            async pull(controller) {
+                try {
+                    const result = await reader.read();
+                    if (finished)
+                        return;
+                    if (result.done) {
+                        finish();
+                        reader.releaseLock();
+                        controller.close();
+                    }
+                    else {
+                        resetIdleDeadline();
+                        controller.enqueue(result.value);
+                    }
+                }
+                catch (error) {
+                    if (finished)
+                        return;
+                    finish();
+                    reader.releaseLock();
+                    controller.error(error);
+                }
+            },
+            async cancel(reason) {
+                if (finished)
+                    return;
+                finish();
+                try {
+                    await reader.cancel(reason);
+                }
+                finally {
+                    reader.releaseLock();
+                }
+            },
+        }, { highWaterMark: 0 });
+        const bounded = new Response(body, {
+            status: response.status,
+            statusText: response.statusText,
+            headers: response.headers,
+        });
+        // Keep fetch metadata while using the bounded stream for body consumers.
+        for (const key of ['url', 'redirected', 'type']) {
+            Object.defineProperty(bounded, key, { value: response[key] });
+        }
+        return bounded;
+    }
+    catch (error) {
+        clearTimeout(timer);
+        if (expired || (error instanceof Error && error.name === 'AbortError')) {
+            throw timeoutError();
+        }
+        throw error;
+    }
+}
+//# sourceMappingURL=response-deadline.js.map

package/dist/shared/llm/spend-ledger.js

@@ -17,6 +17,7 @@
  * connections (one per process) to a WAL-mode DB is exactly the supported
  * cross-process pattern.
  */
+import { createSafeRecord } from '../utils/safe-record.js';
 /** Bucket used for charges recorded without an agent context. */
 export const UNATTRIBUTED_AGENT = '(unattributed)';
 const CREATE_TABLE_SQL = `
@@ -127,7 +128,7 @@ export class SqliteSpendLedger {
                 .prepare(`SELECT COALESCE(agent_type, ?) AS agent, COALESCE(SUM(cost_usd), 0) AS total
              FROM llm_spend WHERE ts >= ? GROUP BY COALESCE(agent_type, ?)`)
                 .all(UNATTRIBUTED_AGENT, nowMs - windowMs, UNATTRIBUTED_AGENT);
-            const out = {};
+            const out = createSafeRecord();
             for (const r of rows)
                 out[r.agent] = r.total;
             return out;
@@ -157,7 +158,7 @@ export class InMemorySpendLedger {
     }
     spentByAgentSince(windowMs, nowMs = Date.now()) {
         const cutoff = nowMs - windowMs;
-        const out = {};
+        const out = createSafeRecord();
         for (const e of this.entries) {
             if (e.ts >= cutoff)
                 out[e.agent] = (out[e.agent] ?? 0) + e.costUsd;

package/dist/shared/metrics/code-metrics.d.ts

@@ -63,6 +63,7 @@ export declare class CodeMetricsAnalyzer {
     detectDuplication(files: string[], minLines?: number): Promise<DuplicationResult>;
     private countLines;
     private calculateCyclomaticComplexity;
+    /** SonarSource cognitive complexity heuristic; see ./cognitive-complexity.ts (#907). */
     private calculateCognitiveComplexity;
     private estimateCyclomaticComplexity;
     private estimateCognitiveComplexity;

package/dist/shared/metrics/code-metrics.js

@@ -6,6 +6,7 @@ import { TypeScriptParser } from '../parsers/index.js';
 import { FileReader } from '../io/index.js';
 import { treeSitterRegistry } from '../parsers/multi-language-parser.js';
 import { getLanguageFromExtension } from '../types/test-frameworks.js';
+import { calculateCognitiveComplexity } from './cognitive-complexity.js';
 // ============================================================================
 // Code Metrics Analyzer
 // ============================================================================
@@ -247,51 +248,9 @@ export class CodeMetricsAnalyzer {
         }
         return complexity;
     }
+    /** SonarSource cognitive complexity heuristic; see ./cognitive-complexity.ts (#907). */
     calculateCognitiveComplexity(code) {
-        let complexity = 0;
-        let nestingLevel = 0;
-        const lines = code.split('\n');
-        for (const line of lines) {
-            const trimmed = line.trim();
-            // Increase nesting
-            if (/\bif\s*\(/.test(trimmed)) {
-                complexity += 1 + nestingLevel;
-                nestingLevel++;
-            }
-            if (/\belse\s+if\s*\(/.test(trimmed)) {
-                complexity += 1 + nestingLevel;
-            }
-            if (/\belse\s*{/.test(trimmed)) {
-                complexity += 1;
-            }
-            if (/\bfor\s*\(/.test(trimmed)) {
-                complexity += 1 + nestingLevel;
-                nestingLevel++;
-            }
-            if (/\bwhile\s*\(/.test(trimmed)) {
-                complexity += 1 + nestingLevel;
-                nestingLevel++;
-            }
-            if (/\bswitch\s*\(/.test(trimmed)) {
-                complexity += 1 + nestingLevel;
-                nestingLevel++;
-            }
-            if (/\bcatch\s*\(/.test(trimmed)) {
-                complexity += 1 + nestingLevel;
-                nestingLevel++;
-            }
-            if (/\?\s*[^:]/.test(trimmed)) {
-                complexity += 1 + nestingLevel; // Ternary
-            }
-            if (/&&|\|\|/.test(trimmed)) {
-                complexity += 1; // Boolean operators
-            }
-            // Track nesting via braces (simplified)
-            const openBraces = (trimmed.match(/{/g) || []).length;
-            const closeBraces = (trimmed.match(/}/g) || []).length;
-            nestingLevel = Math.max(0, nestingLevel + openBraces - closeBraces);
-        }
-        return complexity;
+        return calculateCognitiveComplexity(code);
     }
     estimateCyclomaticComplexity(code) {
         // Fallback heuristic for non-parseable code

package/dist/shared/metrics/cognitive-complexity.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Line-based cognitive complexity heuristic (SonarSource rules, issues #907).
+ * Known gaps (lambdas, labelled jumps, boolean sequences, ...) are tracked in #967.
+ */
+/**
+ * Blank out comments and the contents of string, template and regex literals,
+ * keeping newlines and delimiters, so keywords and braces inside them are not counted.
+ */
+export declare function maskCommentsAndLiterals(code: string): string;
+/**
+ * `if`, loops, `switch`, `catch` and ternaries score +1 plus the nesting level;
+ * `else if` and `else` score a flat +1 (an `else if` is not also an `if`).
+ * Nesting rises only inside the braces of those structures, so a function
+ * body, try block or object literal adds no nesting bonus.
+ */
+export declare function calculateCognitiveComplexity(code: string): number;
+//# sourceMappingURL=cognitive-complexity.d.ts.map

package/dist/shared/metrics/cognitive-complexity.js

@@ -0,0 +1,108 @@
+/**
+ * Line-based cognitive complexity heuristic (SonarSource rules, issues #907).
+ * Known gaps (lambdas, labelled jumps, boolean sequences, ...) are tracked in #967.
+ */
+// A `/` after one of these starts a regex literal; after an operand it is division.
+const REGEX_PREFIX = /(?:^|[(,=:[!&|?{;+\-*%~^]|\b(?:return|typeof|case|do|else|in|of|void|yield|await))$/;
+const blank = (text) => text.replace(/[^\n]/g, ' ');
+/** True when a `/` appended to `out` would start a regex literal (checks only the last token). */
+function regexCanStart(out) {
+    let k = out.length - 1;
+    while (k >= 0 && /\s/.test(out[k]))
+        k--;
+    return REGEX_PREFIX.test(out.slice(Math.max(0, k - 9), k + 1));
+}
+/** Index just past a string, template or regex literal starting at `start`, and whether it closed. */
+function scanLiteral(code, start) {
+    const quote = code[start];
+    let inClass = false;
+    for (let j = start + 1; j < code.length; j++) {
+        const c = code[j];
+        if (c === '\\') {
+            j++;
+            continue;
+        }
+        if (c === '\n' && quote !== '`')
+            return { end: j, closed: false };
+        if (quote === '/' && c === '[')
+            inClass = true;
+        else if (quote === '/' && c === ']')
+            inClass = false;
+        else if (c === quote && !(quote === '/' && inClass))
+            return { end: j + 1, closed: true };
+    }
+    return { end: code.length, closed: false };
+}
+/**
+ * Blank out comments and the contents of string, template and regex literals,
+ * keeping newlines and delimiters, so keywords and braces inside them are not counted.
+ */
+export function maskCommentsAndLiterals(code) {
+    let out = '';
+    let i = 0;
+    while (i < code.length) {
+        const ch = code[i];
+        const next = code[i + 1];
+        if (ch === '/' && (next === '/' || next === '*')) {
+            const close = next === '/' ? code.indexOf('\n', i) : code.indexOf('*/', i + 2);
+            const end = close < 0 ? code.length : next === '/' ? close : close + 2;
+            out += blank(code.slice(i, end));
+            i = end;
+        }
+        else if (ch === '"' || ch === "'" || ch === '`' || (ch === '/' && regexCanStart(out))) {
+            const { end, closed } = scanLiteral(code, i);
+            out += ch + blank(code.slice(i + 1, closed ? end - 1 : end)) + (closed ? code[end - 1] : '');
+            i = end;
+        }
+        else {
+            out += ch;
+            i++;
+        }
+    }
+    return out;
+}
+/**
+ * `if`, loops, `switch`, `catch` and ternaries score +1 plus the nesting level;
+ * `else if` and `else` score a flat +1 (an `else if` is not also an `if`).
+ * Nesting rises only inside the braces of those structures, so a function
+ * body, try block or object literal adds no nesting bonus.
+ */
+export function calculateCognitiveComplexity(code) {
+    const count = (text, pattern) => (text.match(pattern) || []).length;
+    let complexity = 0;
+    const braces = []; // one entry per open `{`: true when it opens a nesting structure
+    let pendingNest = false; // nesting structure whose `{` has not been seen yet
+    for (const line of maskCommentsAndLiterals(code).split('\n')) {
+        let rest = line.trim();
+        // `} else {` / `} catch (e) {`: the previous block closes before this structure is scored.
+        while (rest.startsWith('}')) {
+            braces.pop();
+            rest = rest.slice(1).trimStart();
+        }
+        const nesting = braces.filter(Boolean).length;
+        const flat = count(rest, /\belse\s+if\s*\(/g) + count(rest, /\belse\b(?!\s+if\b)/g);
+        const nested = count(rest, /(?<!\belse\s+)\bif\s*\(/g) + count(rest, /\b(?:for|while|switch|catch)\s*\(/g);
+        complexity += flat + nested * (1 + nesting);
+        if (/\?\s*[^:]/.test(rest)) {
+            complexity += 1 + nesting; // Ternary
+        }
+        if (/&&|\|\|/.test(rest)) {
+            complexity += 1; // Boolean operators
+        }
+        pendingNest ||= flat + nested > 0 || /\bdo\b/.test(rest);
+        for (const ch of rest.match(/[{}]/g) || []) {
+            if (ch === '{') {
+                braces.push(pendingNest);
+                pendingNest = false;
+            }
+            else {
+                braces.pop();
+            }
+        }
+        // A brace-less body (`if (x) return;`) ends the structure without nesting anything.
+        if (rest.endsWith(';'))
+            pendingNest = false;
+    }
+    return complexity;
+}
+//# sourceMappingURL=cognitive-complexity.js.map

package/dist/shared/npm-cli-invocation.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Run npm / npx without a shell on every platform.
+ *
+ * On Windows `npm` and `npx` are `npm.cmd` / `npx.cmd` batch shims. Since the
+ * CVE-2024-27980 fix (Node 18.20.2 / 20.12.2 / 21.7.3+), child_process refuses
+ * to start a `.cmd`/`.bat` without `shell: true` and fails with EINVAL. Turning
+ * the shell on would route caller-supplied arguments through cmd.exe, so we run
+ * the JavaScript CLI that ships next to node.exe with process.execPath instead
+ * (#812, #872).
+ */
+export type NpmCliTool = 'npm' | 'npx';
+/**
+ * Resolve `[executable, leadingArgs]` for npm/npx.
+ *
+ * - POSIX: `[tool, []]` (the real executable on PATH; unchanged behaviour).
+ * - Windows: `[execPath, ['<node dir>\\node_modules\\npm\\bin\\<tool>-cli.js']]`,
+ *   or `null` when that layout is absent. Callers must then fail clearly rather
+ *   than spawn `<tool>.cmd` without a shell.
+ */
+export declare function npmCliInvocation(tool: NpmCliTool, platform?: NodeJS.Platform, execPath?: string, exists?: (path: string) => boolean): [string, string[]] | null;
+//# sourceMappingURL=npm-cli-invocation.d.ts.map

package/dist/shared/npm-cli-invocation.js

@@ -0,0 +1,28 @@
+/**
+ * Run npm / npx without a shell on every platform.
+ *
+ * On Windows `npm` and `npx` are `npm.cmd` / `npx.cmd` batch shims. Since the
+ * CVE-2024-27980 fix (Node 18.20.2 / 20.12.2 / 21.7.3+), child_process refuses
+ * to start a `.cmd`/`.bat` without `shell: true` and fails with EINVAL. Turning
+ * the shell on would route caller-supplied arguments through cmd.exe, so we run
+ * the JavaScript CLI that ships next to node.exe with process.execPath instead
+ * (#812, #872).
+ */
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+/**
+ * Resolve `[executable, leadingArgs]` for npm/npx.
+ *
+ * - POSIX: `[tool, []]` (the real executable on PATH; unchanged behaviour).
+ * - Windows: `[execPath, ['<node dir>\\node_modules\\npm\\bin\\<tool>-cli.js']]`,
+ *   or `null` when that layout is absent. Callers must then fail clearly rather
+ *   than spawn `<tool>.cmd` without a shell.
+ */
+export function npmCliInvocation(tool, platform = process.platform, execPath = process.execPath, exists = existsSync) {
+    if (platform !== 'win32')
+        return [tool, []];
+    // Host path module: it is path.win32 whenever this branch runs for real.
+    const cli = join(dirname(execPath), 'node_modules', 'npm', 'bin', `${tool}-cli.js`);
+    return exists(cli) ? [execPath, [cli]] : null;
+}
+//# sourceMappingURL=npm-cli-invocation.js.map

package/dist/shared/optional-module.js

@@ -33,6 +33,30 @@ export function loadOptionalModule(name, req = defaultRequire) {
     }
     catch (err) {
         if (isModuleAbsent(err)) {
+            // MODULE_NOT_FOUND can name a transitive dependency of a present package.
+            // Resolution checks availability without executing the package again.
+            if (typeof req.resolve === 'function') {
+                try {
+                    req.resolve(name);
+                }
+                catch (resolutionError) {
+                    if (!isModuleAbsent(resolutionError))
+                        throw resolutionError;
+                    return { available: false, degraded: true, name, reason: `optional module "${name}" not installed (running degraded)` };
+                }
+                // Installed optional wrappers may lack the binary for this platform.
+                // Preserve degradation, but identify the missing inner dependency.
+                const message = err.message;
+                const inner = typeof message === 'string'
+                    ? /Cannot find (?:module|package) ['"]([^'"]+)['"]/.exec(message)?.[1]
+                    : undefined;
+                const dependency = inner ? ` its dependency "${inner}" is missing` : ' a dependency is missing';
+                return {
+                    available: false, degraded: true, name,
+                    reason: `optional module "${name}" is installed but${dependency} (running degraded)`,
+                };
+            }
+            // Injected minimal require functions retain the historical absence contract.
             return { available: false, degraded: true, name, reason: `optional module "${name}" not installed (running degraded)` };
         }
         throw err; // present but broken — do NOT mask a real failure (#528)

package/dist/shared/test-runner-args.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Safe argument builders for spawning test runners (issue #909).
+ *
+ * Runner CLIs read some values in ways that can select the wrong tests:
+ * - Jest treats positional TestPathPatterns as regular expressions, so a path
+ *   containing `(`, `[`, `+` or `.` can match other files or miss its own.
+ * - A value that starts with `-` (a test name such as `-x`, or a relative path
+ *   such as `-dash.test.ts`) is parsed as a flag by Jest, Vitest and Mocha.
+ *   Vitest ignores everything after a `--` separator, so a separator alone
+ *   cannot protect positional file filters.
+ *
+ * The rules used here:
+ * - Name filters use the `--flag=value` form, so the value is never a flag.
+ * - File filters are absolute paths, which never start with `-`.
+ * - Jest file filters are regex-escaped and anchored as `^<path>$`, so they
+ *   select exactly one file, and the leading `^` cannot be read as a flag.
+ */
+/** Runners whose test-name filter is a regular expression. */
+export type NameFilterRunner = 'vitest' | 'jest' | 'mocha';
+/** Escape every regular-expression metacharacter in a literal string. */
+export declare function escapeRegExpLiteral(value: string): string;
+/**
+ * Absolute path for a test file. Directory symlinks (for example `/tmp` on
+ * macOS) are resolved the same way runners resolve their root, while the file
+ * name itself is kept. The result never begins with `-`.
+ */
+export declare function runnerFilePath(file: string, cwd?: string): string;
+/**
+ * Jest positional TestPathPattern for `file`. A file matches exactly; a
+ * directory matches every path beneath it but not a sibling that shares its
+ * prefix (`app` vs `app-other`). Separators are normalised to `/`, which Jest
+ * maps to the platform separator.
+ */
+export declare function jestExactPathPattern(file: string, cwd?: string): string;
+/**
+ * Literal test-name filter in `--flag=value` form. Mocha uses `--grep`; Jest
+ * and Vitest use `--testNamePattern` (the long form of `-t`).
+ */
+export declare function nameFilterArg(runner: NameFilterRunner, testName: string): string;
+/** True when a command vector (runner command plus its arguments) runs Jest. */
+export declare function isJestCommand(args: readonly string[]): boolean;
+//# sourceMappingURL=test-runner-args.d.ts.map