mcp-code-context 3.9.1 → 7.0.0

package/dist/src/tools/readHandlers.js

@@ -2,22 +2,28 @@
 import * as path from "node:path";
 import * as fs from "node:fs/promises";
 import { SecurityValidator } from "../core/validator.js";
-import { extractSymbol, readLines, searchPattern, analyzeImpact, searchSymbols, explainSymbol, batchRead } from "../operations/read.js";
+import { extractSymbol, readLines, searchPattern, analyzeImpact, searchSymbols, searchCodeConcept, verifyImportIntegrity, traceTaintFlow, backfillTypes, enforceArchitectureRules, compactContextLedger, generateAstImpactReport, queryCodeAst, incrementalAstDiff, getAstComplexityMatrix, generateAstMocks, detectDeadAstSymbols, resolveLexicalScope, validateSqlAst, astCodemodTranspile, detectAsyncEventloopBlockers, verifyEnvContractDrift, auditErrorHandlingContracts, extractApiRouteMatrix, flattenClassHierarchy, detectCircularDependencies, explainSymbol, batchRead } from "../operations/read.js";
 import { compressRepository } from "../operations/compress.js";
 import { streamFile } from "../utils/streaming.js";
 import { assertNoPendingWriteConflict } from "../utils/toctou.js";
 import { getSession, getCacheManager, getRegistry } from "./context.js";
-import { loadRailsSchema, modelToTable, formatSchemaAnnotation } from "../utils/railsSchema.js";
+import { modelToTable } from "../utils/railsSchema.js";
+import { loadUnifiedVirtualSchema, formatUnifiedSchemaAnnotation } from "../utils/virtualSchema.js";
 import { parseGemfile, formatGemAnnotation } from "../utils/gemfileParser.js";
 import { findMetaprogrammingEntryPoints, formatMetaprogrammingResults } from "../utils/metaprogramming.js";
 import { parseRailsRoutes } from "../utils/railsRoutes.js";
+import { resolveProjectRoot } from "../utils/projectRoot.js";
+import { getImpactedTests } from "../operations/testImpact.js";
+import { getCallHierarchy } from "../operations/callHierarchy.js";
+import { validateWireContract } from "../operations/wireContract.js";
+import { predictSemanticConflicts } from "../operations/conflictPredictor.js";
 export async function handleGetSemanticRepoMap(args) {
-    if (!args.directoryPath || !args.projectRoot) {
-        throw new Error("directoryPath and projectRoot are required (e.g. projectRoot: C:\\code\\mcp-code-context)");
+    if (!args.directoryPath) {
+        throw new Error("directoryPath is required (e.g. C:\\code\\mcp-code-context)");
     }
     const directoryPath = String(args.directoryPath);
-    const projectRoot = String(args.projectRoot);
-    const format = args.format === "markdown" ? "markdown" : "xml";
+    const projectRoot = resolveProjectRoot(args, directoryPath);
+    const format = args.format === "markdown" ? "markdown" : args.format === "html" ? "html" : "xml";
     const validator = new SecurityValidator(projectRoot);
     const validation = await validator.validateFilePath(directoryPath);
     if (!validation.valid) {
@@ -37,7 +43,7 @@ export async function handleGetSemanticRepoMap(args) {
 }
 export async function handleReadFileSurgical(args) {
     const filePath = String(args.filePath);
-    const projectRoot = String(args.projectRoot);
+    const projectRoot = resolveProjectRoot(args, filePath);
     const symbolName = args.symbolName ? String(args.symbolName) : undefined;
     const className = args.className ? String(args.className) : undefined;
     const validator = new SecurityValidator(projectRoot);
@@ -76,37 +82,81 @@ export async function handleReadFileSurgical(args) {
             content = await fs.readFile(validation.resolvedPath, "utf-8");
         }
     }
-    // ActiveRecord Virtual Schema injection
-    if (path.extname(filePath) === ".rb") {
-        // When extracting a symbol, `content` is only the method body — no class declaration.
-        // We need the full file to detect AR inheritance, but guard with stat first to
-        // avoid allocating >5MB files without the streaming guard.
+    // Unified Virtual ORM Schema injection (ActiveRecord, Eloquent, Django, Prisma, Drizzle)
+    const fileExt = path.extname(filePath);
+    if (fileExt === ".rb" || fileExt === ".php" || fileExt === ".py" || fileExt === ".ts" || fileExt === ".tsx" || fileExt === ".js" || fileExt === ".prisma") {
         let sourceForDetection = content;
         if (symbolName) {
             const fileStat = await fs.stat(validation.resolvedPath);
             if (fileStat.size <= 5 * 1024 * 1024) {
                 sourceForDetection = await fs.readFile(validation.resolvedPath, "utf-8");
             }
-            // Files >5MB: skip schema injection for symbol extracts — not worth the memory cost
         }
-        const arMatch = sourceForDetection.match(/class\s+(\w+)\s*<\s*(?:ApplicationRecord|ActiveRecord::Base)/);
-        if (arMatch) {
-            const schema = await loadRailsSchema(projectRoot);
-            if (schema) {
-                const tableName = modelToTable(arMatch[1]);
-                const columns = schema[tableName];
+        let modelName = null;
+        if (fileExt === ".rb") {
+            const m = sourceForDetection.match(/class\s+(\w+)\s*<\s*(?:ApplicationRecord|ActiveRecord::Base)/);
+            if (m) {
+                modelName = m[1];
+            }
+        }
+        else if (fileExt === ".php") {
+            const m = sourceForDetection.match(/class\s+(\w+)\s+extends\s+(?:Model|Authenticatable)/);
+            if (m) {
+                modelName = m[1];
+            }
+        }
+        else if (fileExt === ".py") {
+            const m = sourceForDetection.match(/class\s+(\w+)\s*\([^)]*models\.Model[^)]*\):/);
+            if (m) {
+                modelName = m[1];
+            }
+        }
+        else if (fileExt === ".prisma") {
+            const m = sourceForDetection.match(/model\s+(\w+)\s*\{/);
+            if (m) {
+                modelName = m[1];
+            }
+        }
+        else if (fileExt === ".ts" || fileExt === ".tsx" || fileExt === ".js") {
+            const drizzleM = sourceForDetection.match(/(?:export\s+const\s+(\w+)\s*=\s*)?(?:pgTable|mysqlTable|sqliteTable)\s*\(\s*["']([^"']+)["']/);
+            const prismaM = sourceForDetection.match(/(?:interface|type|class)\s+(\w+)\b/);
+            if (drizzleM) {
+                modelName = drizzleM[2] || drizzleM[1];
+            }
+            else if (prismaM) {
+                modelName = prismaM[1];
+            }
+        }
+        if (modelName) {
+            const unified = await loadUnifiedVirtualSchema(projectRoot, fileExt).catch(() => null);
+            if (unified && unified.schema) {
+                const tableName = modelToTable(modelName);
+                const columns = unified.schema[tableName] || unified.schema[modelName.toLowerCase()] || unified.schema[modelName];
                 if (columns && Object.keys(columns).length > 0) {
-                    content = formatSchemaAnnotation(tableName, columns) + "\n" + content;
+                    content = formatUnifiedSchemaAnnotation(unified.framework, tableName, columns) + "\n" + content;
                 }
             }
         }
     }
-    return { content: [{ type: "text", text: content }] };
+    // Vector 5: Token Budget Efficiency Header
+    let efficiencyHeader = "";
+    try {
+        const stat = await fs.stat(validation.resolvedPath);
+        const rawTokens = Math.max(1, Math.ceil(stat.size / 4));
+        const deliveredTokens = Math.max(1, Math.ceil(content.length / 4));
+        const saved = Math.max(0, rawTokens - deliveredTokens);
+        const ratio = ((saved / rawTokens) * 100).toFixed(1);
+        efficiencyHeader = `<!-- [CodeContext Efficiency]: Raw: ~${rawTokens} tokens | Delivered: ~${deliveredTokens} tokens | Saved: ~${saved} tokens (${ratio}% compression) -->\n\n`;
+    }
+    catch {
+        // Non-blocking header computation
+    }
+    return { content: [{ type: "text", text: efficiencyHeader + content }] };
 }
 export async function handleAnalyzeImpact(args) {
     const filePath = String(args.filePath);
-    const projectRoot = String(args.projectRoot);
-    const rootDir = args.rootDir ? String(args.rootDir) : projectRoot;
+    const projectRoot = resolveProjectRoot(args, filePath);
+    const rootDir = (args.rootDir && args.rootDir !== "undefined") ? String(args.rootDir) : projectRoot;
     const validator = new SecurityValidator(projectRoot);
     const validation = await validator.validateFilePath(filePath);
     if (!validation.valid)
@@ -121,7 +171,7 @@ export async function handleAnalyzeImpact(args) {
 }
 export async function handleReadFileLines(args) {
     const filePath = String(args.filePath);
-    const projectRoot = String(args.projectRoot);
+    const projectRoot = resolveProjectRoot(args, filePath);
     const validator = new SecurityValidator(projectRoot);
     const validation = await validator.validateFilePath(filePath);
     if (!validation.valid)
@@ -140,7 +190,7 @@ export async function handleReadFileLines(args) {
 }
 export async function handleSearchCodePattern(args) {
     const rootDir = String(args.rootDir);
-    const projectRoot = String(args.projectRoot);
+    const projectRoot = resolveProjectRoot(args, rootDir);
     const validator = new SecurityValidator(projectRoot);
     const validation = await validator.validateFilePath(rootDir);
     if (!validation.valid)
@@ -161,7 +211,7 @@ export async function handleSearchCodePattern(args) {
 }
 export async function handleParseFile(args) {
     const filePath = String(args.filePath);
-    const projectRoot = String(args.projectRoot);
+    const projectRoot = resolveProjectRoot(args, filePath);
     const validator = new SecurityValidator(projectRoot);
     const validation = await validator.validateFilePath(filePath);
     if (!validation.valid)
@@ -181,7 +231,7 @@ export async function handleParseFile(args) {
 // NEW-02: search_symbols
 export async function handleSearchSymbols(args) {
     const rootDir = String(args.rootDir);
-    const projectRoot = String(args.projectRoot);
+    const projectRoot = resolveProjectRoot(args, rootDir);
     const validator = new SecurityValidator(projectRoot);
     const validation = await validator.validateFilePath(rootDir);
     if (!validation.valid)
@@ -200,11 +250,486 @@ export async function handleSearchSymbols(args) {
         throw new Error(result.error);
     return { content: [{ type: "text", text: result.content }] };
 }
+// NEW-02b: search_code_concept (v5.0.0)
+export async function handleSearchCodeConcept(args) {
+    const rootDir = (args.rootDir && args.rootDir !== "undefined") ? String(args.rootDir) : undefined;
+    const projectRoot = resolveProjectRoot(args, rootDir);
+    const targetDir = rootDir || projectRoot;
+    const validator = new SecurityValidator(projectRoot);
+    const validation = await validator.validateFilePath(targetDir);
+    if (!validation.valid)
+        throw new Error(validation.error);
+    const registry = getRegistry();
+    const result = await searchCodeConcept({
+        rootDir: validation.resolvedPath,
+        projectRoot,
+        query: String(args.query || ""),
+        threshold: args.threshold !== undefined ? Number(args.threshold) : undefined,
+        maxResults: args.maxResults !== undefined ? Number(args.maxResults) : undefined,
+        fileExtensions: args.fileExtensions,
+        excludeDirs: args.excludeDirs,
+        registry,
+    });
+    if (!result.success)
+        throw new Error(result.error);
+    return { content: [{ type: "text", text: result.content }] };
+}
+// NEW-02c: verify_import_integrity (v5.0.0)
+export async function handleVerifyImportIntegrity(args) {
+    if (!args.filePath)
+        throw new Error("filePath is required for verify_import_integrity");
+    const filePath = String(args.filePath);
+    const projectRoot = resolveProjectRoot(args, filePath);
+    const validator = new SecurityValidator(projectRoot);
+    const validation = await validator.validateFilePath(filePath);
+    if (!validation.valid)
+        throw new Error(validation.error);
+    const registry = getRegistry();
+    const result = await verifyImportIntegrity({
+        filePath: validation.resolvedPath,
+        projectRoot,
+        content: args.content ? String(args.content) : undefined,
+        registry,
+    });
+    if (!result.success)
+        throw new Error(result.error);
+    return { content: [{ type: "text", text: result.content }] };
+}
+// NEW-02d: trace_taint_flow (v5.1.0)
+export async function handleTraceTaintFlow(args) {
+    if (!args.filePath)
+        throw new Error("filePath is required for trace_taint_flow");
+    const filePath = String(args.filePath);
+    const projectRoot = resolveProjectRoot(args, filePath);
+    const validator = new SecurityValidator(projectRoot);
+    const validation = await validator.validateFilePath(filePath);
+    if (!validation.valid && !args.content)
+        throw new Error(validation.error);
+    const resolvedTarget = validation.resolvedPath || path.resolve(projectRoot, filePath);
+    const registry = getRegistry();
+    const result = await traceTaintFlow({
+        filePath: resolvedTarget,
+        projectRoot,
+        sourceParam: args.sourceParam ? String(args.sourceParam) : undefined,
+        dangerousSink: args.dangerousSink ? String(args.dangerousSink) : undefined,
+        content: args.content ? String(args.content) : undefined,
+        registry,
+    });
+    if (!result.success)
+        throw new Error(result.error);
+    return { content: [{ type: "text", text: result.content }] };
+}
+// NEW-02e: backfill_types (v4.5.0)
+export async function handleBackfillTypes(args) {
+    if (!args.filePath)
+        throw new Error("filePath is required for backfill_types");
+    const filePath = String(args.filePath);
+    const projectRoot = resolveProjectRoot(args, filePath);
+    const validator = new SecurityValidator(projectRoot);
+    const validation = await validator.validateFilePath(filePath);
+    if (!validation.valid && !args.content)
+        throw new Error(validation.error);
+    const resolvedTarget = validation.resolvedPath || path.resolve(projectRoot, filePath);
+    const registry = getRegistry();
+    const result = await backfillTypes({
+        filePath: resolvedTarget,
+        projectRoot,
+        symbolName: args.symbolName ? String(args.symbolName) : undefined,
+        targetLanguage: args.targetLanguage,
+        content: args.content ? String(args.content) : undefined,
+        registry,
+    });
+    if (!result.success)
+        throw new Error(result.error);
+    return { content: [{ type: "text", text: result.content }] };
+}
+// NEW-02f: enforce_architecture_rules (v4.6.0)
+export async function handleEnforceArchitectureRules(args) {
+    const filePath = args.filePath ? String(args.filePath) : undefined;
+    const projectRoot = resolveProjectRoot(args, filePath || ".");
+    let resolvedTarget = filePath;
+    if (filePath) {
+        const validator = new SecurityValidator(projectRoot);
+        const validation = await validator.validateFilePath(filePath);
+        if (!validation.valid && !args.content)
+            throw new Error(validation.error);
+        resolvedTarget = validation.resolvedPath || path.resolve(projectRoot, filePath);
+    }
+    const result = await enforceArchitectureRules({
+        filePath: resolvedTarget,
+        projectRoot,
+        rules: args.rules,
+        content: args.content ? String(args.content) : undefined,
+    });
+    if (!result.success)
+        throw new Error(result.error);
+    return { content: [{ type: "text", text: result.content }] };
+}
+// NEW-02g: compact_context_ledger (v4.7.0)
+export async function handleCompactContextLedger(args) {
+    if (!args.filePaths)
+        throw new Error("filePaths is required for compact_context_ledger");
+    const projectRoot = resolveProjectRoot(args, ".");
+    const registry = getRegistry();
+    const result = await compactContextLedger({
+        filePaths: args.filePaths,
+        projectRoot,
+        dropPrivate: args.dropPrivate,
+        includeDocstrings: args.includeDocstrings,
+        content: args.content ? String(args.content) : undefined,
+        registry,
+    });
+    if (!result.success)
+        throw new Error(result.error);
+    return { content: [{ type: "text", text: result.content }] };
+}
+// NEW-02h: generate_ast_impact_report (v5.0.0)
+export async function handleGenerateAstImpactReport(args) {
+    const projectRoot = resolveProjectRoot(args, ".");
+    const result = await generateAstImpactReport({
+        baseBranch: args.baseBranch ? String(args.baseBranch) : undefined,
+        targetBranch: args.targetBranch ? String(args.targetBranch) : undefined,
+        projectRoot,
+        includeTests: args.includeTests !== undefined ? Boolean(args.includeTests) : true,
+        includeArchitecture: args.includeArchitecture !== undefined ? Boolean(args.includeArchitecture) : true,
+    });
+    if (!result.success)
+        throw new Error(result.error);
+    return { content: [{ type: "text", text: result.content }] };
+}
+// NEW-02i: query_code_ast (v5.1.0)
+export async function handleQueryCodeAst(args) {
+    const filePath = args.filePath ? String(args.filePath) : undefined;
+    const projectRoot = resolveProjectRoot(args, filePath || ".");
+    let resolvedTarget = filePath;
+    if (filePath) {
+        const validator = new SecurityValidator(projectRoot);
+        const validation = await validator.validateFilePath(filePath);
+        if (!validation.valid && !args.code)
+            throw new Error(validation.error);
+        resolvedTarget = validation.resolvedPath || path.resolve(projectRoot, filePath);
+    }
+    const registry = getRegistry();
+    const result = await queryCodeAst({
+        filePath: resolvedTarget,
+        projectRoot,
+        query: args.query ? String(args.query) : undefined,
+        template: args.template,
+        code: args.code ? String(args.code) : undefined,
+        limit: args.limit ? Number(args.limit) : undefined,
+        registry,
+    });
+    if (!result.success)
+        throw new Error(result.error);
+    return { content: [{ type: "text", text: result.content }] };
+}
+// NEW-02j: incremental_ast_diff (v5.1.0)
+export async function handleIncrementalAstDiff(args) {
+    const filePath = args.filePath ? String(args.filePath) : undefined;
+    const projectRoot = resolveProjectRoot(args, filePath || ".");
+    let resolvedTarget = filePath;
+    if (filePath) {
+        const validator = new SecurityValidator(projectRoot);
+        const validation = await validator.validateFilePath(filePath);
+        if (!validation.valid && !args.oldCode)
+            throw new Error(validation.error);
+        resolvedTarget = validation.resolvedPath || path.resolve(projectRoot, filePath);
+    }
+    const registry = getRegistry();
+    const result = await incrementalAstDiff({
+        filePath: resolvedTarget,
+        projectRoot,
+        oldCode: args.oldCode ? String(args.oldCode) : undefined,
+        newCode: args.newCode ? String(args.newCode) : undefined,
+        registry,
+    });
+    if (!result.success)
+        throw new Error(result.error);
+    return { content: [{ type: "text", text: result.content }] };
+}
+// NEW-02k: get_ast_complexity_matrix (v5.6.0)
+export async function handleGetAstComplexityMatrix(args) {
+    const filePath = args.filePath ? String(args.filePath) : undefined;
+    const projectRoot = resolveProjectRoot(args, filePath || ".");
+    let resolvedTarget = filePath;
+    if (filePath) {
+        const validator = new SecurityValidator(projectRoot);
+        const validation = await validator.validateFilePath(filePath);
+        if (!validation.valid && !args.code)
+            throw new Error(validation.error);
+        resolvedTarget = validation.resolvedPath || path.resolve(projectRoot, filePath);
+    }
+    const registry = getRegistry();
+    const result = await getAstComplexityMatrix({
+        filePath: resolvedTarget,
+        projectRoot,
+        code: args.code ? String(args.code) : undefined,
+        threshold: args.threshold ? Number(args.threshold) : undefined,
+        registry,
+    });
+    if (!result.success)
+        throw new Error(result.error);
+    return { content: [{ type: "text", text: result.content }] };
+}
+// NEW-02l: generate_ast_mocks (v5.6.0)
+export async function handleGenerateAstMocks(args) {
+    if (!args.symbolName)
+        throw new Error("symbolName is required for generate_ast_mocks");
+    const filePath = args.filePath ? String(args.filePath) : undefined;
+    const projectRoot = resolveProjectRoot(args, filePath || ".");
+    let resolvedTarget = filePath;
+    if (filePath) {
+        const validator = new SecurityValidator(projectRoot);
+        const validation = await validator.validateFilePath(filePath);
+        if (!validation.valid && !args.code)
+            throw new Error(validation.error);
+        resolvedTarget = validation.resolvedPath || path.resolve(projectRoot, filePath);
+    }
+    const registry = getRegistry();
+    const result = await generateAstMocks({
+        filePath: resolvedTarget,
+        projectRoot,
+        symbolName: String(args.symbolName),
+        format: args.format,
+        code: args.code ? String(args.code) : undefined,
+        registry,
+    });
+    if (!result.success)
+        throw new Error(result.error);
+    return { content: [{ type: "text", text: result.content }] };
+}
+// NEW-02m: detect_dead_ast_symbols (v5.7.0)
+export async function handleDetectDeadAstSymbols(args) {
+    const filePath = args.filePath ? String(args.filePath) : undefined;
+    const projectRoot = resolveProjectRoot(args, filePath || ".");
+    let resolvedTarget = filePath;
+    if (filePath) {
+        const validator = new SecurityValidator(projectRoot);
+        const validation = await validator.validateFilePath(filePath);
+        if (!validation.valid && !args.code)
+            throw new Error(validation.error);
+        resolvedTarget = validation.resolvedPath || path.resolve(projectRoot, filePath);
+    }
+    const registry = getRegistry();
+    const result = await detectDeadAstSymbols({
+        filePath: resolvedTarget,
+        projectRoot,
+        code: args.code ? String(args.code) : undefined,
+        registry,
+    });
+    if (!result.success)
+        throw new Error(result.error);
+    return { content: [{ type: "text", text: result.content }] };
+}
+// NEW-02n: resolve_lexical_scope (v5.7.0)
+export async function handleResolveLexicalScope(args) {
+    const filePath = args.filePath ? String(args.filePath) : undefined;
+    const projectRoot = resolveProjectRoot(args, filePath || ".");
+    let resolvedTarget = filePath;
+    if (filePath) {
+        const validator = new SecurityValidator(projectRoot);
+        const validation = await validator.validateFilePath(filePath);
+        if (!validation.valid && !args.code)
+            throw new Error(validation.error);
+        resolvedTarget = validation.resolvedPath || path.resolve(projectRoot, filePath);
+    }
+    const registry = getRegistry();
+    const result = await resolveLexicalScope({
+        filePath: resolvedTarget,
+        projectRoot,
+        code: args.code ? String(args.code) : undefined,
+        proposedRename: args.proposedRename,
+        registry,
+    });
+    if (!result.success)
+        throw new Error(result.error);
+    return { content: [{ type: "text", text: result.content }] };
+}
+// NEW-02o: sql_ast_validator (v6.0.0)
+export async function handleValidateSqlAst(args) {
+    const filePath = args.filePath ? String(args.filePath) : undefined;
+    const projectRoot = resolveProjectRoot(args, filePath || ".");
+    let resolvedTarget = filePath;
+    if (filePath) {
+        const validator = new SecurityValidator(projectRoot);
+        const validation = await validator.validateFilePath(filePath);
+        if (!validation.valid && !args.code)
+            throw new Error(validation.error);
+        resolvedTarget = validation.resolvedPath || path.resolve(projectRoot, filePath);
+    }
+    const registry = getRegistry();
+    const result = await validateSqlAst({
+        filePath: resolvedTarget,
+        projectRoot,
+        code: args.code ? String(args.code) : undefined,
+        registry,
+    });
+    if (!result.success)
+        throw new Error(result.error);
+    return { content: [{ type: "text", text: result.content }] };
+}
+// NEW-02p: ast_codemod_transpile (v6.0.0)
+export async function handleAstCodemodTranspile(args) {
+    if (!args.rule)
+        throw new Error("rule is required for ast_codemod_transpile (e.g. 'cjs-to-esm', 'strip-console')");
+    const filePath = args.filePath ? String(args.filePath) : undefined;
+    const projectRoot = resolveProjectRoot(args, filePath || ".");
+    let resolvedTarget = filePath;
+    if (filePath) {
+        const validator = new SecurityValidator(projectRoot);
+        const validation = await validator.validateFilePath(filePath);
+        if (!validation.valid && !args.code)
+            throw new Error(validation.error);
+        resolvedTarget = validation.resolvedPath || path.resolve(projectRoot, filePath);
+    }
+    const registry = getRegistry();
+    const result = await astCodemodTranspile({
+        filePath: resolvedTarget,
+        projectRoot,
+        rule: args.rule,
+        code: args.code ? String(args.code) : undefined,
+        registry,
+    });
+    if (!result.success)
+        throw new Error(result.error);
+    return { content: [{ type: "text", text: result.content }] };
+}
+// NEW-02q: detect_async_eventloop_blockers (v7.0.0)
+export async function handleDetectAsyncEventloopBlockers(args) {
+    const filePath = args.filePath ? String(args.filePath) : undefined;
+    const projectRoot = resolveProjectRoot(args, filePath || ".");
+    let resolvedTarget = filePath;
+    if (filePath) {
+        const validator = new SecurityValidator(projectRoot);
+        const validation = await validator.validateFilePath(filePath);
+        if (!validation.valid && !args.code)
+            throw new Error(validation.error);
+        resolvedTarget = validation.resolvedPath || path.resolve(projectRoot, filePath);
+    }
+    const registry = getRegistry();
+    const result = await detectAsyncEventloopBlockers({
+        filePath: resolvedTarget,
+        projectRoot,
+        code: args.code ? String(args.code) : undefined,
+        registry,
+    });
+    if (!result.success)
+        throw new Error(result.error);
+    return { content: [{ type: "text", text: result.content }] };
+}
+// NEW-02r: verify_env_contract_drift (v7.0.0)
+export async function handleVerifyEnvContractDrift(args) {
+    const filePath = args.filePath ? String(args.filePath) : undefined;
+    const projectRoot = resolveProjectRoot(args, filePath || ".");
+    let resolvedTarget = filePath;
+    if (filePath) {
+        const validator = new SecurityValidator(projectRoot);
+        const validation = await validator.validateFilePath(filePath);
+        if (!validation.valid && !args.code)
+            throw new Error(validation.error);
+        resolvedTarget = validation.resolvedPath || path.resolve(projectRoot, filePath);
+    }
+    const registry = getRegistry();
+    const result = await verifyEnvContractDrift({
+        filePath: resolvedTarget,
+        projectRoot,
+        code: args.code ? String(args.code) : undefined,
+        envExampleContent: args.envExampleContent ? String(args.envExampleContent) : undefined,
+        registry,
+    });
+    if (!result.success)
+        throw new Error(result.error);
+    return { content: [{ type: "text", text: result.content }] };
+}
+// NEW-02s: audit_error_handling_contracts (v7.0.0)
+export async function handleAuditErrorHandlingContracts(args) {
+    const filePath = args.filePath ? String(args.filePath) : undefined;
+    const projectRoot = resolveProjectRoot(args, filePath || ".");
+    let resolvedTarget = filePath;
+    if (filePath) {
+        const validator = new SecurityValidator(projectRoot);
+        const validation = await validator.validateFilePath(filePath);
+        if (!validation.valid && !args.code)
+            throw new Error(validation.error);
+        resolvedTarget = validation.resolvedPath || path.resolve(projectRoot, filePath);
+    }
+    const registry = getRegistry();
+    const result = await auditErrorHandlingContracts({
+        filePath: resolvedTarget,
+        projectRoot,
+        code: args.code ? String(args.code) : undefined,
+        registry,
+    });
+    if (!result.success)
+        throw new Error(result.error);
+    return { content: [{ type: "text", text: result.content }] };
+}
+// NEW-02t: extract_api_route_matrix (v7.0.0)
+export async function handleExtractApiRouteMatrix(args) {
+    const filePath = args.filePath ? String(args.filePath) : undefined;
+    const projectRoot = resolveProjectRoot(args, filePath || ".");
+    let resolvedTarget = filePath;
+    if (filePath) {
+        const validator = new SecurityValidator(projectRoot);
+        const validation = await validator.validateFilePath(filePath);
+        if (!validation.valid && !args.code)
+            throw new Error(validation.error);
+        resolvedTarget = validation.resolvedPath || path.resolve(projectRoot, filePath);
+    }
+    const registry = getRegistry();
+    const result = await extractApiRouteMatrix({
+        filePath: resolvedTarget,
+        projectRoot,
+        code: args.code ? String(args.code) : undefined,
+        registry,
+    });
+    if (!result.success)
+        throw new Error(result.error);
+    return { content: [{ type: "text", text: result.content }] };
+}
+// NEW-02u: flatten_class_hierarchy (v7.0.0)
+export async function handleFlattenClassHierarchy(args) {
+    const filePath = args.filePath ? String(args.filePath) : undefined;
+    const projectRoot = resolveProjectRoot(args, filePath || ".");
+    let resolvedTarget = filePath;
+    if (filePath) {
+        const validator = new SecurityValidator(projectRoot);
+        const validation = await validator.validateFilePath(filePath);
+        if (!validation.valid && !args.code)
+            throw new Error(validation.error);
+        resolvedTarget = validation.resolvedPath || path.resolve(projectRoot, filePath);
+    }
+    const registry = getRegistry();
+    const result = await flattenClassHierarchy({
+        filePath: resolvedTarget,
+        projectRoot,
+        className: args.className ? String(args.className) : undefined,
+        code: args.code ? String(args.code) : undefined,
+        registry,
+    });
+    if (!result.success)
+        throw new Error(result.error);
+    return { content: [{ type: "text", text: result.content }] };
+}
+// NEW-02v: detect_circular_dependencies (v7.0.0)
+export async function handleDetectCircularDependencies(args) {
+    const projectRoot = resolveProjectRoot(args, ".");
+    const registry = getRegistry();
+    const result = await detectCircularDependencies({
+        projectRoot,
+        filesMap: args.filesMap,
+        filePaths: args.filePaths,
+        registry,
+    });
+    if (!result.success)
+        throw new Error(result.error);
+    return { content: [{ type: "text", text: result.content }] };
+}
 // NEW-03: explain_symbol
 export async function handleExplainSymbol(args) {
     const filePath = String(args.filePath);
-    const projectRoot = String(args.projectRoot);
-    const rootDir = args.rootDir ? String(args.rootDir) : projectRoot;
+    const projectRoot = resolveProjectRoot(args, filePath);
+    const rootDir = (args.rootDir && args.rootDir !== "undefined") ? String(args.rootDir) : projectRoot;
     const validator = new SecurityValidator(projectRoot);
     const validation = await validator.validateFilePath(filePath);
     if (!validation.valid)
@@ -227,7 +752,7 @@ export async function handleExplainSymbol(args) {
 }
 // NEW-05: batch_read
 export async function handleBatchRead(args) {
-    const projectRoot = String(args.projectRoot);
+    const projectRoot = resolveProjectRoot(args);
     const reads = args.reads;
     const validator = new SecurityValidator(projectRoot);
     // Validate all paths upfront
@@ -248,7 +773,7 @@ export async function handleBatchRead(args) {
 }
 // R7: get_gemfile_context — parse Gemfile and return known gem behaviors
 export async function handleGetGemfileContext(args) {
-    const projectRoot = String(args.projectRoot);
+    const projectRoot = resolveProjectRoot(args);
     const validator = new SecurityValidator(projectRoot);
     const rootValidation = await validator.validateFilePath(projectRoot);
     if (!rootValidation.valid)
@@ -268,11 +793,12 @@ export async function handleGetGemfileContext(args) {
 }
 // R3: find_metaprogramming — scan for dynamic method generation entry points
 export async function handleFindMetaprogramming(args) {
-    const projectRoot = String(args.projectRoot);
-    const target = args.filePath ? String(args.filePath) : args.rootDir ? String(args.rootDir) : projectRoot;
+    const target = args.filePath ? String(args.filePath) : args.rootDir ? String(args.rootDir) : undefined;
+    const projectRoot = resolveProjectRoot(args, target);
+    const resolvedTarget = target ?? projectRoot;
     const isFile = Boolean(args.filePath);
     const validator = new SecurityValidator(projectRoot);
-    const validation = await validator.validateFilePath(target);
+    const validation = await validator.validateFilePath(resolvedTarget);
     if (!validation.valid)
         throw new Error(validation.error);
     const matches = await findMetaprogrammingEntryPoints({
@@ -284,7 +810,7 @@ export async function handleFindMetaprogramming(args) {
 }
 // R2: get_rails_routes — parse config/routes.rb and return route map
 export async function handleGetRailsRoutes(args) {
-    const projectRoot = String(args.projectRoot);
+    const projectRoot = resolveProjectRoot(args);
     const validator = new SecurityValidator(projectRoot);
     const rootValidation = await validator.validateFilePath(projectRoot);
     if (!rootValidation.valid)
@@ -295,4 +821,85 @@ export async function handleGetRailsRoutes(args) {
     }
     return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
 }
+// TIA: get_impacted_tests — map modified AST symbols to target test suites
+export async function handleGetImpactedTests(args) {
+    if (!args.filePath)
+        throw new Error("filePath is required");
+    const filePath = String(args.filePath);
+    const projectRoot = resolveProjectRoot(args, filePath);
+    const symbolName = args.symbolName ? String(args.symbolName) : undefined;
+    const validator = new SecurityValidator(projectRoot);
+    const validation = await validator.validateFilePath(filePath);
+    if (!validation.valid)
+        throw new Error(validation.error);
+    const result = await getImpactedTests({
+        filePath: validation.resolvedPath,
+        symbolName,
+        projectRoot,
+    });
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+}
+// 3-Hop Call Hierarchy: get_call_hierarchy
+export async function handleGetCallHierarchy(args) {
+    if (!args.filePath)
+        throw new Error("filePath is required");
+    if (!args.symbolName)
+        throw new Error("symbolName is required");
+    const filePath = String(args.filePath);
+    const symbolName = String(args.symbolName);
+    const projectRoot = resolveProjectRoot(args, filePath);
+    const direction = args.direction || "both";
+    const maxHops = args.maxHops ? Number(args.maxHops) : 3;
+    const validator = new SecurityValidator(projectRoot);
+    const validation = await validator.validateFilePath(filePath);
+    if (!validation.valid)
+        throw new Error(validation.error);
+    const result = await getCallHierarchy({
+        filePath: validation.resolvedPath,
+        symbolName,
+        direction,
+        maxHops,
+        projectRoot,
+    });
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+}
+// Cross-Language Wire Contract: validate_wire_contract
+export async function handleValidateWireContract(args) {
+    if (!args.frontendFile)
+        throw new Error("frontendFile is required");
+    const frontendFile = String(args.frontendFile);
+    const projectRoot = resolveProjectRoot(args, frontendFile);
+    const backendFile = args.backendFile ? String(args.backendFile) : undefined;
+    const endpoint = args.endpoint ? String(args.endpoint) : undefined;
+    const validator = new SecurityValidator(projectRoot);
+    const feVal = await validator.validateFilePath(frontendFile);
+    if (!feVal.valid)
+        throw new Error(feVal.error);
+    let bePath = undefined;
+    if (backendFile) {
+        const beVal = await validator.validateFilePath(backendFile);
+        if (!beVal.valid)
+            throw new Error(beVal.error);
+        bePath = beVal.resolvedPath;
+    }
+    const result = await validateWireContract({
+        frontendFile: feVal.resolvedPath,
+        backendFile: bePath,
+        endpoint,
+        projectRoot,
+    });
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+}
+// Semantic Merge Conflict Predictor: predict_semantic_conflicts
+export async function handlePredictSemanticConflicts(args) {
+    const projectRoot = resolveProjectRoot(args);
+    const baseBranch = args.baseBranch ? String(args.baseBranch) : undefined;
+    const targetBranch = args.targetBranch ? String(args.targetBranch) : undefined;
+    const result = await predictSemanticConflicts({
+        baseBranch,
+        targetBranch,
+        projectRoot,
+    });
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+}
 //# sourceMappingURL=readHandlers.js.map